@miliastry/quasar 1.0.0

package/src/Visitors/JSONExporter.ts

@@ -0,0 +1,66 @@
+/**
+ * DocumentEngine — JSONExporter
+ *
+ * Exports the Document Model to JSON.
+ * Useful for:
+ * - Saving/loading documents in a structured format
+ * - Sending over the wire (collaboration)
+ * - Debugging and inspecting the document tree
+ * - Import/export between different tools
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+import { Visitor } from './Visitor'
+
+export interface JSONDocument {
+  version: number
+  kind: string
+  nodes: JSONNode[]
+  metadata?: Record<string, unknown>
+}
+
+export interface JSONNode {
+  id: string
+  kind: string
+  text: string
+  version: number
+  children: JSONNode[]
+  attributes?: Record<string, unknown>
+  metadata?: Record<string, unknown>
+  range?: { start: number; end: number }
+}
+
+export class JSONExporter extends Visitor<string> {
+  /**
+   * Export a RedNode tree to a JSON string.
+   */
+  visit(node: RedNode): string {
+    return JSON.stringify(this.toJSON(node), null, 2)
+  }
+
+  /**
+   * Export to a JSON object.
+   */
+  toJSON(node: RedNode): JSONDocument {
+    return {
+      version: node.version,
+      kind: node.kind,
+      nodes: node.children.map(c => this.serializeNode(c)),
+    }
+  }
+
+  private serializeNode(node: RedNode): JSONNode {
+    return {
+      id: node.id,
+      kind: node.kind,
+      text: node.text,
+      version: node.version,
+      children: node.children.map(c => this.serializeNode(c)),
+      attributes: node.metadata?.tagName
+        ? { tag: node.metadata.tagName as string }
+        : undefined,
+      metadata: Object.keys(node.metadata).length > 0 ? node.metadata : undefined,
+      range: { start: node.range.start, end: node.range.end },
+    }
+  }
+}

package/src/Visitors/MarkdownExporter.ts

@@ -0,0 +1,99 @@
+/**
+ * DocumentEngine — MarkdownExporter
+ *
+ * Exports the Document Model to Markdown.
+ * Demonstrates the format-agnostic power of the engine:
+ * BBCode in → DocumentModel → Markdown out.
+ *
+ * A single visitor, no parser changes needed.
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+import { Visitor } from './Visitor'
+
+export class MarkdownExporter extends Visitor<string> {
+  visit(node: RedNode): string {
+    return this.exportNode(node).replace(/(?:\r?\n){3,}/g, '\n\n')
+  }
+
+  export(node: RedNode): string {
+    return this.visit(node)
+  }
+
+  private exportNode(node: RedNode, depth: number = 0): string {
+    if (node.children.length === 0 && node.kind === 'text') {
+      return node.text
+    }
+
+    if (node.kind === 'document') {
+      return node.children.map(c => this.exportNode(c, depth)).join('')
+    }
+
+    const content = node.children.map(c => this.exportNode(c, depth)).join('')
+
+    switch (node.kind) {
+      case 'bold': return `**${content}**`
+      case 'italic': return `*${content}*`
+      case 'underline': return content
+      case 'strikethrough': return `~~${content}~~`
+      case 'inline_code': return `\`${content}\``
+      case 'code': return `\`\`\`\n${content}\n\`\`\``
+      case 'spoiler': return `||${content}||`
+      case 'color': return content
+      case 'font_size': return content
+      case 'font': return content
+      case 'heading': return `${'#'.repeat(Math.min(depth + 1, 6))} ${content}`
+      case 'center': return content
+      case 'right': return content
+      case 'left': return content
+      case 'url': return `[${content}](${this.extractValue(node) || content})`
+      case 'email': return `[${content}](mailto:${this.extractValue(node) || content})`
+      case 'profile': return `[${content}](https://osu.ppy.sh/users/${this.extractValue(node) || content})`
+      case 'image': return `![Image](${node.text || ''})`
+      case 'video': return `[🎥 YouTube Video](https://youtube.com/watch?v=${node.text || ''})`
+      case 'audio': return `[🎵 Audio](${node.text || ''})`
+      case 'quote': return `> **${this.extractValue(node) || 'Quote'}**\n> ${content.replace(/\\n/g, '\n> ')}`
+      case 'notice': return `> [!NOTE]\n> ${content.replace(/\\n/g, '\n> ')}`
+      case 'spoilerbox': return `**${this.renderTitleMarkdown(node) || 'Spoiler'}**\n${content}`
+      case 'box':
+      case 'boxw': return `**${this.renderTitleMarkdown(node) || 'Box'}**\n${content}`
+      case 'list': return content
+      case 'list_item': return `${'  '.repeat(Math.max(0, depth - 1))}- ${content.trim()}`
+      case 'spacing': return '\n'
+      case 'empty_line': return '\n'
+      case 'text':
+      default: return content || node.text || ''
+    }
+  }
+
+  private renderTitleMarkdown(node: RedNode): string {
+    const titleNodes = node.metadata?.titleNodes as RedNode[] | undefined
+    if (titleNodes && titleNodes.length > 0) {
+      return titleNodes.map(c => this.exportNode(c, 0)).join('')
+    }
+    return (node.metadata?.title as string) || this.extractValue(node) || ''
+  }
+
+  /**
+   * Read a BBCode tag's `=VALUE` attribute.
+   *
+   * This previously read `node.properties` / `node.attributes`, neither of
+   * which exists on RedNode — so it silently returned `undefined` for every
+   * node and every call site fell through to its placeholder. That is why
+   * Markdown export dropped link targets and quote/box titles.
+   */
+  private extractValue(node: RedNode): string | undefined {
+    const text = node.text || ''
+    const eqIdx = text.indexOf('=')
+    if (eqIdx < 0) return undefined
+
+    let value = text.slice(eqIdx + 1)
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    return value || undefined
+  }
+}

package/src/Visitors/SVGRenderer.ts

@@ -0,0 +1,35 @@
+import { RedNode } from '../Syntax/RedNode'
+import { Visitor } from './Visitor'
+import { HTMLRenderer } from './HTMLRenderer'
+import type { VisitorContext } from './Visitor'
+
+/**
+ * SVGRenderer (Runtime ForeignObject Strategy)
+ * 
+ * Instead of attempting to calculate CSS layouts manually,
+ * this runtime renderer wraps the exact HTML output in an SVG <foreignObject>.
+ * 
+ * This gives 100% precision with zero DOM scanning overhead for real-time previews.
+ */
+export class SVGRenderer extends Visitor<string> {
+  private htmlRenderer = new HTMLRenderer()
+
+  visit(node: RedNode, context?: VisitorContext): string {
+    if (context) this.context = context
+    return this.render(node)
+  }
+
+  render(root: RedNode): string {
+    const htmlContent = this.htmlRenderer.render(root)
+    
+    // We wrap the HTML in a foreignObject. The container gets the standard BBCode preview classes
+    // so it inherits all global CSS (osu.css, tailwind, etc.) perfectly.
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%">
+  <foreignObject width="100%" height="100%">
+    <div xmlns="http://www.w3.org/1999/xhtml" class="bb-preview bbcode-preview text-sm leading-relaxed text-[#E8E0E4] wrap-break-word min-w-0 w-full h-full p-4 box-border">
+      ${htmlContent}
+    </div>
+  </foreignObject>
+</svg>`
+  }
+}

package/src/Visitors/TiptapExporter.ts

@@ -0,0 +1,145 @@
+/**
+ * DocumentEngine — TiptapExporter
+ *
+ * Exports the Document Model to Tiptap (ProseMirror) JSON format.
+ * This proves how easily Quasar's AST bridges to visual WYSIWYG editors.
+ *
+ * Tiptap uses a JSON format structured like:
+ * {
+ *   type: "doc",
+ *   content: [
+ *     {
+ *       type: "paragraph",
+ *       content: [
+ *         { type: "text", text: "Hello ", marks: [{ type: "bold" }] }
+ *       ]
+ *     }
+ *   ]
+ * }
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+import { Visitor } from './Visitor'
+
+export interface TiptapNode {
+  type: string
+  attrs?: Record<string, any>
+  content?: TiptapNode[]
+  marks?: TiptapMark[]
+  text?: string
+}
+
+export interface TiptapMark {
+  type: string
+  attrs?: Record<string, any>
+}
+
+export class TiptapExporter extends Visitor<string> {
+  visit(node: RedNode): string {
+    return JSON.stringify(this.toTiptap(node), null, 2)
+  }
+
+  toTiptap(node: RedNode): TiptapNode {
+    if (node.kind === 'document') {
+      return {
+        type: 'doc',
+        content: this.processChildren(node.children, []),
+      }
+    }
+    return this.processNode(node, [])
+  }
+
+  private processChildren(children: RedNode[], marks: TiptapMark[]): TiptapNode[] {
+    const content: TiptapNode[] = []
+    
+    for (const child of children) {
+      // empty_line and spacing become empty paragraphs or brs depending on context
+      if (child.kind === 'empty_line' || child.kind === 'spacing') {
+        continue // Simplification: in a real bridge, these would divide paragraphs
+      }
+      content.push(this.processNode(child, marks))
+    }
+
+    return content
+  }
+
+  private processNode(node: RedNode, activeMarks: TiptapMark[]): TiptapNode {
+    // 1. Check if this node is a mark (inline formatting)
+    const newMark = this.kindToMark(node)
+    if (newMark) {
+      const nextMarks = [...activeMarks, newMark]
+      // Inline tags shouldn't exist as blocks in Tiptap, they just wrap text
+      // We return a text node if it's the leaf, otherwise we flatten children
+      if (node.children.length === 1 && node.children[0].kind === 'text') {
+         return {
+           type: 'text',
+           text: node.children[0].text,
+           marks: nextMarks
+         }
+      } else if (node.children.length === 0) {
+         return { type: 'text', text: '', marks: nextMarks }
+      }
+      
+      // Simplification: if multiple children, we wrap them all in this mark
+      // Tiptap actually expects a flat list of text nodes with marks.
+      // So this requires flattening. For MVP, we return a custom block or flat text.
+      // We will just create a custom inline block for now.
+      return {
+        type: 'text',
+        text: node.children.map(c => c.text || '').join(''),
+        marks: nextMarks
+      }
+    }
+
+    // 2. Leaf Text Node
+    if (node.kind === 'text') {
+      return {
+        type: 'text',
+        text: node.text,
+        marks: activeMarks.length > 0 ? activeMarks : undefined
+      }
+    }
+
+    // 3. Block Nodes
+    return {
+      type: this.kindToBlockType(node.kind),
+      attrs: Object.keys(node.metadata).length > 0 ? node.metadata : undefined,
+      content: node.children.length > 0 ? this.processChildren(node.children, activeMarks) : undefined
+    }
+  }
+
+  private kindToMark(node: RedNode): TiptapMark | null {
+    switch (node.kind) {
+      case 'bold': return { type: 'bold' }
+      case 'italic': return { type: 'italic' }
+      case 'underline': return { type: 'underline' }
+      case 'strikethrough': return { type: 'strike' }
+      case 'inline_code': return { type: 'code' }
+      case 'color': return { type: 'textStyle', attrs: { color: node.metadata.color } }
+      case 'url': return { type: 'link', attrs: { href: node.metadata.href } }
+      case 'gradient': 
+      case 'rainbow':
+      case 'grow':
+      case 'sinewave':
+        return { type: 'miliastryEffect', attrs: { effect: node.kind, ...node.metadata } }
+    }
+    return null
+  }
+
+  private kindToBlockType(kind: string): string {
+    const map: Record<string, string> = {
+      heading: 'heading',
+      paragraph: 'paragraph',
+      quote: 'blockquote',
+      code: 'codeBlock',
+      list: 'bulletList',
+      list_item: 'listItem',
+      image: 'image',
+      center: 'centerBlock',
+      notice: 'noticeBlock',
+      box: 'boxBlock',
+      spoilerbox: 'spoilerboxBlock'
+    }
+    return map[kind] ?? 'paragraph'
+  }
+}

package/src/Visitors/Visitor.ts

@@ -0,0 +1,48 @@
+/**
+ * DocumentEngine — Visitor
+ *
+ * Base visitor pattern for traversing the Red Tree.
+ * All exporters and renderers extend this.
+ *
+ * Instead of switch statements on tag names, use the visitor pattern.
+ * New languages/exporters don't modify existing code.
+ *
+ * Inspired by SwiftSyntax's Visitor pattern.
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+
+export interface VisitorContext {
+  source: string
+  options: Record<string, unknown>
+}
+
+export abstract class Visitor<T = string> {
+  protected context: VisitorContext = { source: '', options: {} }
+
+  /**
+   * Visit a node and produce an output value.
+   */
+  abstract visit(node: RedNode, context?: VisitorContext): T
+
+  /**
+   * Visit all children and combine results.
+   */
+  visitChildren(node: RedNode, separator: string = ''): T[] {
+    return node.children.map(child => this.visit(child))
+  }
+
+  /**
+   * Get the text content of a node.
+   */
+  getText(node: RedNode): string {
+    return node.text || node.children.map(c => c.text).join('')
+  }
+
+  /**
+   * Set the visitor context.
+   */
+  setContext(context: VisitorContext): void {
+    this.context = context
+  }
+}

package/src/Visitors/index.ts

@@ -0,0 +1,9 @@
+export { Visitor } from './Visitor'
+export type { VisitorContext } from './Visitor'
+export { BBCodeExporter } from './BBCodeExporter'
+export { HTMLRenderer } from './HTMLRenderer'
+export { morphHTML } from './DOMMorpher'
+export { MarkdownExporter } from './MarkdownExporter'
+export { JSONExporter } from './JSONExporter'
+export { SVGRenderer } from './SVGRenderer'
+export type { JSONDocument, JSONNode } from './JSONExporter'

package/src/Visuals/BoxDrawer.ts

@@ -0,0 +1,175 @@
+/**
+ * DocumentEngine — BoxDrawer
+ *
+ * Drawer-style open/close animation for the `<details>` elements that
+ * HTMLRenderer emits for `[box]` and `[spoilerbox]`. The box grows downwards
+ * and progressively uncovers its content, which stays anchored under the
+ * summary instead of popping in all at once.
+ *
+ * This lives in Quasar rather than in a consumer because Quasar is what emits
+ * the `<details>` in the first place — the same reason `morphHTML` lives here.
+ * Any host that renders Quasar output gets the behaviour by binding it once.
+ *
+ * Why not CSS: while a `<details>` is closed its content is not rendered, so
+ * there is no height to interpolate between. `::details-content` combined with
+ * `interpolate-size: allow-keywords` would solve it, but it is Chromium-only in
+ * practice and hosts running on WebKit would silently lose the animation.
+ * Measuring the real height and driving it with the Web Animations API works on
+ * every engine.
+ *
+ * Heights are measured, not computed from summary + padding + borders, because
+ * that arithmetic breaks as soon as a theme puts margins on the summary or the
+ * boxes are nested. Toggling `open` and reading the rect yields the exact
+ * height the element will settle at, whatever the stylesheet does.
+ */
+
+export interface BoxDrawerOptions {
+  /** Length of a full open or close, in milliseconds. Partial travel is scaled down. */
+  durationMs?: number
+  /** CSS easing function. */
+  easing?: string
+}
+
+/** Time for the full collapsed↔expanded travel; shorter distances scale down. */
+const DEFAULT_DURATION_MS = 400
+/** Floor so an interruption near the end still reads as motion, not a snap. */
+const MIN_DURATION_MS = 120
+/** easeOutCubic — fast to start, settles softly, no overshoot. */
+const DEFAULT_EASING = 'cubic-bezier(0.33, 1, 0.68, 1)'
+
+interface DrawerState {
+  animation: Animation
+  /** Where the box is heading, which is what a new click has to reverse. */
+  opening: boolean
+  /**
+   * Inline `overflow` from before the FIRST animation of a chain. Carried
+   * across interruptions so a reversal restores the author's value and not the
+   * `hidden` that the previous animation had just installed.
+   */
+  restoreOverflow: string
+}
+
+/** In-flight state per element; a WeakMap so morphed-away nodes are freed. */
+const running = new WeakMap<HTMLDetailsElement, DrawerState>()
+
+function prefersReducedMotion(): boolean {
+  return typeof window !== 'undefined'
+    && typeof window.matchMedia === 'function'
+    && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
+/**
+ * Animate one `<details>` to its opposite state, reversing cleanly when it is
+ * already mid-animation.
+ *
+ * Exported so hosts that toggle boxes programmatically (a keyboard command, an
+ * "expand all" action) go through the same animation as a click.
+ */
+export function toggleBoxWithDrawer(
+  details: HTMLDetailsElement,
+  options: BoxDrawerOptions = {}
+): void {
+  if (typeof details.animate !== 'function' || prefersReducedMotion()) {
+    details.open = !details.open
+    return
+  }
+
+  // Height as painted right now — read BEFORE cancelling, so an interrupted
+  // animation resumes from where the eye last saw it instead of snapping.
+  const from = details.getBoundingClientRect().height
+
+  const previous = running.get(details)
+  const restoreOverflow = previous ? previous.restoreOverflow : details.style.overflow
+
+  // Direction comes from the running animation's intent, never from
+  // `details.open`: a closing box is kept open so its content stays visible, so
+  // reading the attribute would report "open" and close it a second time,
+  // making a mid-close click impossible to reverse.
+  const opening = previous ? !previous.opening : !details.open
+
+  previous?.animation.cancel()
+
+  // Both extremes are needed to scale the duration by the distance actually
+  // travelled. `open` is left true either way so the content stays visible
+  // while the box grows or shrinks over it.
+  let collapsed: number
+  let expanded: number
+  if (details.open) {
+    expanded = details.getBoundingClientRect().height
+    details.open = false
+    collapsed = details.getBoundingClientRect().height
+    details.open = true
+  } else {
+    collapsed = details.getBoundingClientRect().height
+    details.open = true
+    expanded = details.getBoundingClientRect().height
+  }
+
+  const to = opening ? expanded : collapsed
+  details.style.overflow = 'hidden'
+
+  // A reversal 90% of the way open only has 10% left to travel; running the
+  // full duration over it would crawl.
+  const fullTravel = expanded - collapsed
+  const ratio = fullTravel > 0 ? Math.min(Math.abs(to - from) / fullTravel, 1) : 1
+  const duration = Math.max(
+    (options.durationMs ?? DEFAULT_DURATION_MS) * ratio,
+    MIN_DURATION_MS
+  )
+
+  const animation = details.animate(
+    { height: [`${from}px`, `${to}px`] },
+    { duration, easing: options.easing ?? DEFAULT_EASING }
+  )
+  running.set(details, { animation, opening, restoreOverflow })
+
+  /**
+   * `finish` and `cancel` are dispatched asynchronously, so by the time either
+   * lands a newer toggle may already own the element. Without this guard the
+   * outgoing animation strips the incoming one's `overflow: hidden` mid-flight
+   * — content spilling out of a small box — or applies its own `open` and
+   * freezes the box shut.
+   */
+  const settle = (finished: boolean) => {
+    if (running.get(details)?.animation !== animation) return
+    running.delete(details)
+    if (finished) details.open = opening
+    details.style.overflow = restoreOverflow
+  }
+
+  animation.addEventListener('finish', () => settle(true))
+  animation.addEventListener('cancel', () => settle(false))
+}
+
+/**
+ * Intercept the native toggle of every box inside `root`.
+ *
+ * The listener is delegated rather than attached per box: hosts typically feed
+ * the preview through `morphHTML` on every keystroke, and per-element listeners
+ * would be torn down and re-attached continuously.
+ *
+ * @param root - container holding the rendered BBCode
+ * @returns disposer that removes the listener
+ */
+export function bindBoxDrawer(
+  root: HTMLElement,
+  options: BoxDrawerOptions = {}
+): () => void {
+  const handleClick = (e: MouseEvent) => {
+    const target = e.target as HTMLElement | null
+    const summary = target?.closest('summary')
+    if (!summary) return
+
+    const details = summary.parentElement
+    if (!(details instanceof HTMLDetailsElement)) return
+    if (!root.contains(details)) return
+
+    // Enter/Space on the summary also arrive here as a click, so the keyboard
+    // is covered without a separate handler.
+    e.preventDefault()
+    toggleBoxWithDrawer(details, options)
+  }
+
+  root.addEventListener('click', handleClick)
+  return () => root.removeEventListener('click', handleClick)
+}

package/src/Visuals/index.ts

@@ -0,0 +1,42 @@
+/**
+ * DocumentEngine — Visuals
+ *
+ * Catálogo de estilos visuales por plataforma para la previsualización
+ * de BBCode. Cada plataforma puede tener su propia apariencia sin
+ * modificar el renderer HTML.
+ *
+ * Uso:
+ *   // Importar como CSS directo (soportado por Next.js, Vite, Webpack):
+ *   import 'MiliastryPlatform/DocumentEngine/Visuals/osu.css'
+ *
+ *   // O desde un componente React:
+ *   import 'MiliastryPlatform/DocumentEngine/Visuals/osu.css'
+ *   // Luego en el JSX: <div className="bbcode-preview" ...
+ *
+ * Para cambiar de tema visual, solo cambia el import del CSS.
+ *
+ * Temas disponibles:
+ *   - osu  → Estilo visual inspirado en los foros de osu!
+ *   - miliastry → Estilo por defecto de Miliastry (próximamente)
+ */
+
+export { bindBoxDrawer, toggleBoxWithDrawer } from './BoxDrawer'
+export type { BoxDrawerOptions } from './BoxDrawer'
+
+export const visualThemes = [
+  {
+    id: 'osu',
+    name: 'osu! Forum Style',
+    description: 'Estilo visual inspirado en los foros de osu!',
+    cssFile: 'osu.css',
+  },
+  {
+    id: 'lyne',
+    name: 'Lyne Style',
+    description: 'Estilo visual cyberpunk con cortes a 45° inspirado en Lyne',
+    cssFile: 'lyne.css',
+  },
+] as const
+
+export type VisualThemeId = (typeof visualThemes)[number]['id']
+