@miliastry/quasar 1.0.6 → 1.2.0

package/src/Visitors/BBCodeExporter.ts

@@ -12,6 +12,12 @@ import { RedNode } from '../Syntax/RedNode'
 import { Visitor } from './Visitor'
 import type { VisitorContext } from './Visitor'
 import { TagRegistry, type TagDefinition } from '../Model/TagRegistry'
+import {
+  toTokenResolver,
+  resolveTokenValue,
+  type TokenResolverFn,
+  type TokenSource,
+} from '../Tokens'
 
 /**
  * Export target for BBCodeExporter.
@@ -21,8 +27,42 @@ import { TagRegistry, type TagDefinition } from '../Model/TagRegistry'
  */
 export type ExportTarget = 'osu' | 'miliastry' | 'lyne'
 
+export interface BBCodeExporterOptions {
+  registry?: TagRegistry
+  target?: ExportTarget
+  tokens?: TokenSource
+  resolveTokens?: boolean
+}
+
+export type BBCodeExportOptions = {
+  target?: ExportTarget
+  tokens?: TokenSource
+  resolveTokens?: boolean
+}
+
+/**
+ * Referencia a un token de diseño dentro de un texto: `$nombre`.
+ *
+ * A nivel de módulo porque el sitio caliente es la rama de nodo TEXTO, la
+ * clase de nodo más frecuente de cualquier documento: un literal de expresión
+ * regular ahí dentro construye un `RegExp` por nodo. Había además tres copias
+ * idénticas del mismo patrón repartidas por el fichero.
+ */
+const TOKEN_REF_RE = /\$([a-zA-Z_][a-zA-Z0-9_-]*)/g
+
+/** Sustituye cada `$token` por su valor; deja intacto el que no resuelva. */
+function expandTokenRefs(text: string, resolve: TokenResolverFn): string {
+  // `indexOf` antes que `replace`: la inmensa mayoría de los textos no lleva
+  // ningún `$`, y así no se pone en marcha el motor de expresiones regulares.
+  if (text.indexOf('$') === -1) return text
+  return text.replace(TOKEN_REF_RE, (match, name: string) => {
+    const resolved = resolve(name) ?? resolve(match)
+    return resolved !== undefined ? resolved : match
+  })
+}
+
 /** Miliastry-native effect tags that osu! doesn't support natively */
-const MILIASTRY_INTERNAL_TAGS = new Set(['gradient', 'grow', 'sinewave', 'rainbow'])
+const MILIASTRY_INTERNAL_TAGS = new Set(['gradient', 'grow', 'sinewave', 'rainbow', 'paint'])
 
 /**
  * Tags que existen SOLO en Miliastry (registrados en el TagRegistry) y que
@@ -39,6 +79,9 @@ export const LYNE_ONLY_TAGS = new Set([
   'boxw', 'wnotice', 'tables', 'table_row', 'table_col', 'table_th', 'gallery', 'columns',
   'separator', 'scroll', 'sup', 'sub', 'abbr', 'mark', 'kbd', 'tooltip', 'flip',
   'raw', 'plain', 'guild', 'map', 'align', 'effect', 'anim', 'container', 'style_tag',
+  'neon', 'shimmer', 'glitch', 'typewriter', 'wave', 'fire', 'ice', 'ghost', 'glow',
+  'outline', 'emboss', 'engrave', 'pulse', 'bounce', 'shake', 'levitate', 'fade-in', 'fade-out',
+  'card', 'glass', 'neon-box', 'square', 'row', 'col', 'th',
 ])
 
 /**
@@ -89,11 +132,17 @@ const KIND_TO_TAG_NAME: Record<string, string> = {
   flower: 'flower',
   gradient: 'gradient',
   grow: 'grow',
+  rainbow: 'rainbow',
+  sinewave: 'sinewave',
+  paint: 'paint',
   align: 'align',
   tables: 'tables',
   table_row: 'row',
   table_col: 'col',
   table_th: 'th',
+  row: 'row',
+  col: 'col',
+  th: 'th',
   gallery: 'gallery',
   columns: 'columns',
   separator: 'separator',
@@ -111,18 +160,147 @@ const KIND_TO_TAG_NAME: Record<string, string> = {
   anim: 'anim',
   container: 'container',
   style_tag: 'style',
+  neon: 'neon',
+  shimmer: 'shimmer',
+  glitch: 'glitch',
+  typewriter: 'typewriter',
+  wave: 'wave',
+  fire: 'fire',
+  ice: 'ice',
+  ghost: 'ghost',
+  glow: 'glow',
+  outline: 'outline',
+  emboss: 'emboss',
+  engrave: 'engrave',
+  pulse: 'pulse',
+  bounce: 'bounce',
+  shake: 'shake',
+  levitate: 'levitate',
+  'fade-in': 'fade-in',
+  'fade-out': 'fade-out',
+  card: 'card',
+  glass: 'glass',
+  'neon-box': 'neon-box',
+  square: 'square',
+}
+
+
+/**
+ * Whether a parsed attribute actually carries a value worth re-emitting.
+ *
+ * The parser stores an empty string for the attribute of a bare tag, so a
+ * plain `[box]` arrives here with `rawTitle: ''` rather than `undefined`.
+ * The guards below used to test `!== undefined`, which an empty string
+ * passes — exporting `[box]` as `[box=]` and `[quote]` as `[quote=""]`.
+ * Both are corruption, not normalization: bare boxes and quotes are
+ * ordinary BBCode and must round-trip untouched.
+ */
+function hasAttrValue(value: unknown): boolean {
+  return value !== undefined && value !== null && String(value) !== ''
+}
+
+/**
+ * Expande un cuerpo hexadecimal a los 6 dígitos que exige osu, o `null` si no
+ * es un hex de longitud reconocible (3, 4, 6 u 8).
+ *
+ * El canal alfa se descarta a propósito: osu no soporta transparencia en
+ * ninguna forma, así que la alternativa a perderlo es publicar un `[color=…]`
+ * que su parser rechaza y deja como texto literal en la página.
+ */
+function expandHexForOsu(body: string): string | null {
+  if (!/^[0-9a-fA-F]+$/.test(body)) return null
+  switch (body.length) {
+    case 3:
+      return body[0] + body[0] + body[1] + body[1] + body[2] + body[2]
+    case 4:
+      // RGBA corto: expandimos RGB y tiramos el alfa.
+      return body[0] + body[0] + body[1] + body[1] + body[2] + body[2]
+    case 6:
+      // Ya es legal: se devuelve tal cual, sin tocar mayúsculas del autor.
+      return body
+    case 8:
+      // RGBA largo: los dos últimos dígitos son el alfa.
+      return body.slice(0, 6)
+    default:
+      return null
+  }
 }
 
+/**
+ * `target` decide si además de convertir `rgb()` hay que adaptar el hex a la
+ * gramática de osu (`BBCodeForDB::parseColour`), que sólo acepta `#` + 6
+ * dígitos hex o una secuencia puramente alfabética. Para 'miliastry' y 'lyne'
+ * el comportamiento es el de siempre: no se reescribe nada.
+ */
+function normalizeColorToHex(color: string, target: ExportTarget = 'miliastry'): string {
+  if (!color) return color
+  const trimmed = color.trim()
+  // Un hex ya es canónico: bajarlo a minúsculas reescribía `[color=#FF0000]`
+  // del autor en cada exportación, y `Analysis/RoundTrip` fija lo contrario.
+  if (trimmed.startsWith('#')) {
+    if (target !== 'osu') return trimmed
+    const expanded = expandHexForOsu(trimmed.slice(1))
+    return expanded === null ? trimmed : `#${expanded}`
+  }
+
+  const rgbMatch = trimmed.match(/^rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)$/i)
+  if (rgbMatch) {
+    const r = parseInt(rgbMatch[1], 10).toString(16).padStart(2, '0')
+    const g = parseInt(rgbMatch[2], 10).toString(16).padStart(2, '0')
+    const b = parseInt(rgbMatch[3], 10).toString(16).padStart(2, '0')
+    return `#${r}${g}${b}`.toLowerCase()
+  }
+
+  // Hex desnudo: osu exige el `#`, así que `ff0000` se publicaría roto. Sólo
+  // lo tratamos como hex si trae algún dígito; una palabra puramente
+  // alfabética (`red`, y también `beef`, que es hex válido) ya matchea la
+  // alternativa alfabética de osu y no hay que tocarla.
+  if (target === 'osu' && /\d/.test(trimmed)) {
+    const expanded = expandHexForOsu(trimmed)
+    if (expanded !== null) return `#${expanded}`
+  }
+
+  return trimmed
+}
 
 export class BBCodeExporter extends Visitor<string> {
   private registry: TagRegistry
   private depth: number = 0
   private target: ExportTarget
+  private tokens?: TokenSource
+  private tokenResolver?: TokenResolverFn
+  private explicitResolveTokens?: boolean
+  /**
+   * El resolvedor a aplicar en ESTE recorrido, o `null` si no hay expansión.
+   *
+   * Se decide una vez en `visit`, no por nodo: `shouldResolveTokens()` da la
+   * misma respuesta para todo el documento, y se estaba llamando en la rama
+   * de nodo texto, la más frecuente que hay.
+   */
+  private expandTokens: TokenResolverFn | null = null
 
-  constructor(registry: TagRegistry = new TagRegistry(), target: ExportTarget = 'osu') {
+  constructor(
+    registryOrOptions?: TagRegistry | BBCodeExporterOptions,
+    target: ExportTarget = 'osu',
+    options?: BBCodeExporterOptions | { tokens?: TokenSource; resolveTokens?: boolean },
+  ) {
     super()
-    this.registry = registry
-    this.target = target
+    if (registryOrOptions && !(registryOrOptions instanceof TagRegistry) && !('get' in registryOrOptions)) {
+      const opts = registryOrOptions as BBCodeExporterOptions
+      this.registry = opts.registry ?? new TagRegistry()
+      this.target = opts.target ?? 'osu'
+      this.tokens = opts.tokens
+      this.tokenResolver = toTokenResolver(opts.tokens)
+      this.explicitResolveTokens = opts.resolveTokens
+    } else {
+      this.registry = (registryOrOptions as TagRegistry) ?? new TagRegistry()
+      this.target = target
+      if (options) {
+        this.tokens = options.tokens
+        this.tokenResolver = toTokenResolver(options.tokens)
+        this.explicitResolveTokens = options.resolveTokens
+      }
+    }
   }
 
   /**
@@ -132,30 +310,95 @@ export class BBCodeExporter extends Visitor<string> {
     this.target = target
   }
 
+  setTokens(tokens?: TokenSource): void {
+    this.tokens = tokens
+    this.tokenResolver = toTokenResolver(tokens)
+  }
+
+  getTokens(): TokenSource | undefined {
+    return this.tokens
+  }
+
+  getTokenResolver(): TokenResolverFn | undefined {
+    return this.tokenResolver
+  }
+
+  private shouldResolveTokens(): boolean {
+    if (this.explicitResolveTokens !== undefined) {
+      return this.explicitResolveTokens
+    }
+    return this.target === 'osu'
+  }
+
   /**
    * Export a RedNode tree to BBCode.
    */
   visit(node: RedNode, context?: VisitorContext): string {
     if (context) this.context = context
     this.depth = 0
+    this.expandTokens =
+      this.tokenResolver !== undefined && this.shouldResolveTokens() ? this.tokenResolver : null
     return this.exportNode(node)
   }
 
   /**
    * Export the entire document to BBCode.
-   * Optionally override the export target for this specific call.
+   * Optionally override the export target or options for this specific call.
    */
-  export(root: RedNode, target?: ExportTarget): string {
-    if (target !== undefined) this.target = target
+  export(
+    root: RedNode,
+    targetOrOptions?: ExportTarget | BBCodeExportOptions,
+    options?: BBCodeExportOptions,
+  ): string {
+    if (typeof targetOrOptions === 'string') {
+      this.target = targetOrOptions
+      if (options?.tokens !== undefined) {
+        this.setTokens(options.tokens)
+      }
+      if (options?.resolveTokens !== undefined) {
+        this.explicitResolveTokens = options.resolveTokens
+      }
+    } else if (targetOrOptions && typeof targetOrOptions === 'object') {
+      if (targetOrOptions.target !== undefined) {
+        this.target = targetOrOptions.target
+      }
+      if (targetOrOptions.tokens !== undefined) {
+        this.setTokens(targetOrOptions.tokens)
+      }
+      if (targetOrOptions.resolveTokens !== undefined) {
+        this.explicitResolveTokens = targetOrOptions.resolveTokens
+      }
+    }
     return this.visit(root)
   }
 
+  /**
+   * Exporta los hijos directos y los concatena.
+   *
+   * Reemplaza el `children.map(...).join('')`, que asignaba un cierre y un
+   * array intermedio de N cadenas en cada nivel del árbol. `HTMLRenderer`
+   * hizo este mismo cambio y dejó la nota; el exportador se quedó atrás, y es
+   * el camino que corre bajo un límite de 60.000 caracteres.
+   */
+  private exportChildren(node: RedNode): string {
+    const children = node.children
+    let out = ''
+    for (let i = 0; i < children.length; i++) out += this.exportNode(children[i])
+    return out
+  }
+
   private exportNode(node: RedNode): string {
+    // Un cierre que no cerró nada no vuelve al source. Escribirlo hacía que el
+    // siguiente parseo lo leyera otra vez como etiqueta viva, y el documento no
+    // convergía al reexportarlo.
+    if (node.kind === 'discarded_tag') return ''
+
     const tagDef = this.registry.getByKind(node.kind)
 
     // Text nodes
     if (node.kind === 'text') {
       let out = node.text
+      if (this.expandTokens !== null) out = expandTokenRefs(out, this.expandTokens)
       const style = node.metadata?.style as Record<string, string> | undefined
       if (style) {
         // Envolvemos desde adentro hacia afuera (o al revés, no importa mucho para osu)
@@ -163,8 +406,20 @@ export class BBCodeExporter extends Visitor<string> {
         if (style.fontStyle === 'italic') out = `[i]${out}[/i]`
         if (style.textDecoration === 'underline') out = `[u]${out}[/u]`
         if (style.textDecoration === 'line-through') out = `[s]${out}[/s]`
-        if (style.color) out = `[color=${style.color}]${out}[/color]`
-        if (style.fontSize) out = `[size=${style.fontSize}]${out}[/size]`
+        if (style.color) {
+          let col = style.color
+          if (this.shouldResolveTokens() && col.startsWith('$')) {
+            col = resolveTokenValue(col, this.tokenResolver)
+          }
+          out = `[color=${normalizeColorToHex(col, this.target)}]${out}[/color]`
+        }
+        if (style.fontSize) {
+          let size = style.fontSize
+          if (this.shouldResolveTokens() && size.startsWith('$')) {
+            size = resolveTokenValue(size, this.tokenResolver)
+          }
+          out = `[size=${size}]${out}[/size]`
+        }
         // Se pueden seguir sumando estilos dinámicos
       }
       return out
@@ -172,7 +427,7 @@ export class BBCodeExporter extends Visitor<string> {
 
     // Document root
     if (node.kind === 'document') {
-      return node.children.map(c => this.exportNode(c)).join('')
+      return this.exportChildren(node)
     }
 
     // Custom tag handlers from registry
@@ -196,7 +451,7 @@ export class BBCodeExporter extends Visitor<string> {
     // Default BBCode serialization
     let tagName = this.kindToTagName(node.kind)
     const attrs = this.getTagAttributes(node)
-    const content = node.children.map(c => this.exportNode(c)).join('')
+    const content = this.exportChildren(node)
 
     if (!tagName) {
       if (node.kind === 'spacing') return '\n'
@@ -246,38 +501,78 @@ export class BBCodeExporter extends Visitor<string> {
         if (tag?.properties) {
           const parts: string[] = []
           for (const prop of tag.properties) {
-            const val = node.metadata[prop.name]
+            let val = node.metadata[prop.name]
             if (val !== undefined && val !== null) {
+              if (this.shouldResolveTokens() && typeof val === 'string' && val.startsWith('$')) {
+                val = resolveTokenValue(val, this.tokenResolver)
+              }
               parts.push(`${prop.name}=${val}`)
             }
           }
           if (parts.length > 0) return `=${parts[0]}`
         }
-      } else if (node.kind === 'font_size' && node.metadata.size !== undefined) {
-        return `=${node.metadata.size}`
-      } else if (node.kind === 'color' && node.metadata.color !== undefined) {
-        return `=${node.metadata.color}`
-      } else if (node.kind === 'font' && node.metadata.font !== undefined) {
-        return `=${node.metadata.font}`
+      } else if (node.kind === 'font_size' && hasAttrValue(node.metadata.size)) {
+        let size = String(node.metadata.size)
+        if (this.shouldResolveTokens() && size.startsWith('$')) {
+          size = resolveTokenValue(size, this.tokenResolver)
+        }
+        return `=${size}`
+      } else if (node.kind === 'color' && hasAttrValue(node.metadata.color)) {
+        let color = String(node.metadata.color)
+        if (this.shouldResolveTokens() && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${normalizeColorToHex(color, this.target)}`
+      } else if (node.kind === 'font' && hasAttrValue(node.metadata.font)) {
+        let font = String(node.metadata.font)
+        if (this.shouldResolveTokens() && font.startsWith('$')) {
+          font = resolveTokenValue(font, this.tokenResolver)
+        }
+        return `=${font}`
       } else if (node.kind === 'url' && node.metadata.href !== undefined) {
         return `=${node.metadata.href}`
-      } else if (node.kind === 'email' && node.metadata.href !== undefined) {
-        return `=${(node.metadata.href as string).replace('mailto:', '')}`
-      } else if (node.kind === 'quote' && node.metadata.source !== undefined) {
-        return `="${node.metadata.source}"`
-      } else if ((node.kind === 'box' || node.kind === 'boxw' || node.kind === 'spoilerbox') && (node.metadata.rawTitle !== undefined || node.metadata.title !== undefined)) {
-        const titleVal = node.metadata.rawTitle !== undefined ? node.metadata.rawTitle : node.metadata.title
+      } else if (node.kind === 'email' && hasAttrValue(node.metadata.href)) {
+        // The parser prefixes the address with `mailto:`, so a bare `[email]`
+        // arrives as exactly that prefix and nothing else — test the address.
+        const address = (node.metadata.href as string).replace('mailto:', '')
+        return address === '' ? '' : `=${address}`
+      } else if (node.kind === 'quote' && hasAttrValue(node.metadata.source)) {
+        let src = String(node.metadata.source)
+        if (this.expandTokens !== null) src = expandTokenRefs(src, this.expandTokens)
+        return `="${src}"`
+      } else if (node.kind === 'box' || node.kind === 'boxw' || node.kind === 'spoilerbox') {
+        // `rawTitle` is the source spelling; `title` is the parsed one, which
+        // falls back to a synthetic "Box"/"Spoiler" when the tag is bare. Only
+        // the raw form can be trusted to reproduce the input, so it wins.
+        const raw = node.metadata.rawTitle
+        let titleVal = String((raw !== undefined ? raw : node.metadata.title) ?? '')
+        if (this.expandTokens !== null) titleVal = expandTokenRefs(titleVal, this.expandTokens)
         // `[box=Title:#hex]`: el color se guardó aparte en metadata; se vuelve
         // a añadir aquí para que el round-trip no pierda el sufijo.
-        const color = node.metadata.color as string | undefined
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        // A bare `[box]` has neither, and must stay bare.
+        if (titleVal === '' && !color) return ''
         return `=${titleVal}${color ? `:${color}` : ''}`
       } else if ((node.kind === 'notice' || node.kind === 'wnotice') && node.metadata.color !== undefined) {
-        return `=${node.metadata.color}`
+        let color = String(node.metadata.color)
+        if (this.shouldResolveTokens() && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${color}`
       } else if (node.kind === 'tables' && node.metadata.variant !== undefined) {
-        const color = node.metadata.color as string | undefined
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
         return `=${node.metadata.variant}${color ? `:${color}` : ''}`
       } else if (node.kind === 'columns' && node.metadata.columns !== undefined) {
-        const color = node.metadata.color as string | undefined
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
         return `=${node.metadata.columns}${color ? `:${color}` : ''}`
       } else if (node.kind === 'separator' && node.metadata.variant !== undefined) {
         return `=${node.metadata.variant}`
@@ -294,22 +589,60 @@ export class BBCodeExporter extends Visitor<string> {
       } else if (node.kind === 'align' && node.metadata.align !== undefined) {
         return `=${node.metadata.align}`
       } else if (node.kind === 'effect' && node.metadata.effectType !== undefined) {
-        return `=${node.metadata.effectType}`
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${node.metadata.effectType}${color ? `:${color}` : ''}`
       } else if (node.kind === 'image' && node.metadata.imgAttr !== undefined) {
         return `=${node.metadata.imgAttr}`
       } else if (node.kind === 'anim' && node.metadata.animType !== undefined) {
         return `=${node.metadata.animType}`
       } else if (node.kind === 'container' && node.metadata.containerType !== undefined) {
-        return `=${node.metadata.containerType}`
+        let color = node.metadata.color as string | undefined
+        if (this.shouldResolveTokens() && color && color.startsWith('$')) {
+          color = resolveTokenValue(color, this.tokenResolver)
+        }
+        return `=${node.metadata.containerType}${color ? `:${color}` : ''}`
       } else if (node.kind === 'style_tag' && node.metadata.style !== undefined) {
-        return `=${node.metadata.style}`
+        let style = String(node.metadata.style)
+        if (this.shouldResolveTokens()) {
+          style = style.replace(/\$([a-zA-Z0-9_.-]+)/g, (match) => {
+            return resolveTokenValue(match, this.tokenResolver)
+          })
+        }
+        return `=${style}`
+      } else if (hasAttrValue(node.metadata.value)) {
+        let val = String(node.metadata.value)
+        if (this.shouldResolveTokens() && val.startsWith('$')) {
+          val = resolveTokenValue(val, this.tokenResolver)
+        }
+        return `=${val}`
+      } else if (hasAttrValue(node.metadata.raw)) {
+        let raw = String(node.metadata.raw)
+        if (this.shouldResolveTokens() && raw.startsWith('$')) {
+          raw = resolveTokenValue(raw, this.tokenResolver)
+        }
+        return `=${raw}`
       }
     }
 
     // Fallback: check node text for attribute info
     const text = node.text || ''
     if (text.startsWith('=') || text.startsWith(' ')) {
-      // The text is exactly the attributes string (e.g. "=50" or " min=50 max=200")
+      if (node.kind === 'color' && text.startsWith('=')) {
+        let col = text.slice(1)
+        if (this.shouldResolveTokens() && col.startsWith('$')) {
+          col = resolveTokenValue(col, this.tokenResolver)
+        }
+        return `=${normalizeColorToHex(col, this.target)}`
+      }
+      if (this.shouldResolveTokens() && text.startsWith('=')) {
+        let val = text.slice(1)
+        if (val.startsWith('$')) {
+          return `=${resolveTokenValue(val, this.tokenResolver)}`
+        }
+      }
       return text
     }