@longform/async 0.0.29

package/lib/longform.ts

@@ -0,0 +1,1045 @@
+import type { Directive, Doc, Element, ElementCtx, FragmentRef, FragmentType, LongformArgs, OutputMode, ParsedLongform, TargetType, WorkingElement, WorkingFragment } from "./types.ts";
+
+const LINE = 0
+    , INDENT = 1
+    , DIRECTIVE_KEY = 2
+    , DIRECTIVE = 3
+    , DIRECTIVE_INLINE_ARGS = 4
+    , ID_TYPE = 5
+    , ID = 6
+    , FRAGMENT_TYPE = 7
+    , ELEMENT = 8
+    , ATTR = 9
+    , COMMENT = 10
+    , sniffTestRe = /^((?:  )*)(?:(@)([a-z][a-z\-]*(?::[a-z][a-z\-]*)?)(?:(?:(?::: (.*)))|(?:::)? *)?|(##?)([a-z][a-z\-]*)(?: ?(?: +([\["]))? *|(?: *))?|(?:[a-z][a-z\-]*(?::[a-z][a-z\-])?.*(::).*)|(?:(\[)[a-z][a-z\-]?.*(?:=.+)?\]\w*)|(--).*|(.+))$/gmi
+
+    // captures a single element definition which could be in a chain.
+    // id, class and attributes are matched as a single block for a later loop
+    // if in chained situation the regexp will need to be looped over for each element
+    // we know the element is the last if the final capture group has a positive match
+    // or if the line is consumed by the regexp.
+    , outerRe = /([a-z][\w\-]*(?::[a-z][\w\-]*)?)((?:(?:[^:])|(?::(?!:)))*)::(?: (?:({{?)|(.*)))?/gi
+
+    // captures each id, class and attribute declaration in an element
+    , innerRe = /(?:\.([a-z][\w\-]+)|#([a-z][\w\-]+)|\[([a-z][a-z\-]+(?::[a-z][a-z|\-]*)?)(?:=(?:"([^"]+)"|'([^']+)'|([^\]]+)))?\])/gi
+    , attributeRe = /((?:\ \ )+)\[(\w[\w-]*(?::\w[\w-]*)?)(?:=([^\n]+))?\]/
+    , attributeOrInlineDirectiveRe = /^\s*@([a-z][\w\-]*(?::[a-z][\w\-]*)?)\s*$/i
+    , idRe = /((?:\ \ )+)?#(#)?([\w\-]+)(?: ([\["]))?/i
+    , refRe = /#\[([\w\-]+)\]/g
+    , escapeRe = /([&<>"'#\[\]{}])/g
+    , templateLinesRe = /^(\ \ )?([^\n]+)$/gm
+    , templateRe = /#(#)?{([a-z][\w\-]*(?::[a-z][\w\-]*)?)}|#\[([a-z][\w\-]*(?::[a-z][\w\-]*)?)\]/g
+    , preformatClose = new Set(['}', '}}'])
+    , voids = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wrb']);
+
+
+const entities = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&apos;',
+//  '#': '&num;',
+//  '[': '&lbrak;',
+//  ']': '&rbrak;',
+//  '{': '&rbrace;',
+//  '}': '&lbrace;',
+};
+
+function escape(value: string): string {
+  return value.replace(escapeRe, (match) => {
+    return entities[match as keyof typeof entities] ?? match;
+  });
+}
+
+function makeElement(indent: number = 0): WorkingElement {
+  return {
+    indent,
+    key: undefined,
+    id: undefined,
+    tag: undefined as unknown as string,
+    class: undefined,
+    text: undefined,
+    attrs: {},
+    html: '',
+    mount: undefined,
+    chain: undefined as unknown as WorkingElement[],
+    beforeRender: undefined,
+  };
+}
+
+function makeFragment(type: FragmentType = 'bare'): WorkingFragment {
+  return {
+    id: undefined as unknown as string,
+    type,
+    html: '',
+    template: false,
+    mountable: false,
+    els: [],
+    refs: [],
+    mountPoints: [],
+  };
+}
+
+const directiveValidator = /^[a-z][a-z\-]*\:[a-z][a-z\-]*$/i;
+
+
+/**
+ * Parses a longform document into a object containing the root and fragments
+ * in the output format.
+ *
+ * @param input - The Longform document to parse.
+ * @param args - Arguments for the Longform parser.
+ */
+export async function longform(
+  input: string,
+  args?: LongformArgs,
+): Promise<ParsedLongform> {
+  let skipping: boolean = false
+    , verbatimText: string = ''
+    , verbatimIndent: number = 0
+    , verbatimType: number = 0
+    , lastIndex: number = 0
+    , element: WorkingElement = makeElement()
+    , fragment: WorkingFragment = makeFragment()
+    , directive!: {
+        name: string;
+        inlineArgs: string;
+        def?: Directive,
+      }
+    // the root fragment
+    , root: WorkingFragment | null = null
+    , id: string | undefined = args?.id
+    , type: string | undefined = args?.type
+    , lang: string | undefined = args?.lang
+    , dir: string | undefined = args?.dir
+    , doc!: Doc
+    , asyncCount: number = 0
+    , m1: RegExpExecArray | null = null
+    , m2: RegExpExecArray | null = null
+    , m3: RegExpExecArray | null = null
+    // ids of claimed fragments
+  const claimed: Set<string> = new Set()
+    , meta: Record<string, unknown> = Object.assign({}, args?.meta)
+    , data: Record<string, unknown> = {}
+    , outputMode: OutputMode = args?.outputMode ?? 'doc'
+    , targetType: TargetType = args?.targetType ?? 'text/html'
+    , parsed: Map<string, WorkingFragment> = new Map(
+      Object.entries(args?.fragments as unknown as Record<string, WorkingFragment> ?? {})
+    )
+    , output: ParsedLongform = { outputMode: args?.outputMode ?? 'doc' } as unknown as ParsedLongform
+    , directives: Record<string, Directive> = {
+        id: { attr: ctx => ctx.doc.id },
+        type: { attr: ctx => ctx.doc.type },
+        dir: { attr: ctx => ctx.doc.dir },
+        lang: { attr: ctx => ctx.doc.lang },
+    }
+    , promises: Array<Promise<void>> = []
+
+  let key: string | undefined = args?.key;
+  
+  if (key == null && args?.annotations === 'obscure') {
+    const arr = new Uint8Array(10);
+
+    crypto.getRandomValues(arr);
+
+    // If this fails you are probably using it in an environment
+    // where `toHex()` is not supported. If this is a browser environment
+    // it is likely you do not need obscure data attributes. They
+    // are specifically for the purpose of safely server rendering 
+    // fragments that the client application needs to identify.
+    //
+    // If that doesn't apply you can pass a key in the args that
+    // is cryptographically random generated along with the
+    // `'obscure'` annotation argument.
+    // deno-lint-ignore no-explicit-any
+    key = (arr as any).toHex().toLowerCase();
+  } else if (key == null && args?.annotations === 'predictable') {
+    key = 'lf';
+  }
+
+  output.fragments = {};
+  output.templates = {};
+
+  if (args?.directives != null) {
+    const entries = Object.entries(args.directives);
+
+    let e: [string, Directive];
+    
+    for (let i = 0, l = entries.length; i < l; i++) {
+      e = entries[i];
+
+      if (!directiveValidator.test(e[0])) {
+        console.warn(`Invalid custom directive name '$e{[0]}'`);
+
+        continue;
+      }
+  
+      directives[e[0]] = e[1];
+    }
+  }
+
+  // This is a hack to allow open verbatim blocks to detect
+  // when they close via an extra step in the loop.
+  input += '\n  ';
+  sniffTestRe.lastIndex = 0;
+  main: while ((m1 = sniffTestRe.exec(input))) {
+    if (m1[COMMENT] === '--') {
+      continue;
+    } else if (fragment.template) {
+      fragment.html += m1[0];
+    }
+
+    const indent = m1[INDENT].length / 2;
+
+    // only one root fragment is allowed. Skip until beginning of next fragment / directive.
+    if (skipping && indent !== 0) continue;
+    // I hear avoiding branching is faster than avoiding assignments...
+    skipping = false;
+
+    // verbatim blocks collect the string as is as a continuous block
+    // and do processing on it once the full block has been collected.
+    if (verbatimType !== 0) {
+      if (indent >= verbatimIndent && (
+        // text verbatim type should exit when other Longform constructs begin.
+        verbatimType !== 1 || 
+        (m1[DIRECTIVE_KEY] ?? m1[ID_TYPE] ?? m1[ELEMENT] ?? m1[ATTR]) === undefined
+      )) {
+        if (verbatimType === 1) {
+          // Text verbatim blocks join with blank spaces 
+          verbatimText += ' ' + m1[0].trim();
+        } else {
+          if (verbatimText !== '') verbatimText += '\n';
+          
+          // other verbatim blocks normalize the Longform indent of the block away
+          verbatimText += m1[0].replace('  '.repeat(verbatimIndent), '');
+        }
+        continue;
+      } else if (m1[0].trim() === '' &&
+                 input.length !== m1.index + m1[0].length) {
+        // blank line in verbatim are ignored by text types
+        if (verbatimType !== 1) verbatimText += '\n';
+
+        continue;
+      } else {
+        // verbatim block is finished
+        switch (verbatimType) {
+          case 1:
+            // text
+            fragment.html += verbatimText;
+
+            // locate reference points in text
+            while ((m2 = refRe.exec(verbatimText))) {
+              const start = fragment.html.length + m2.index - verbatimText.length;
+
+              fragment.refs.push({
+                id: m2[1],
+                start,
+                end: start + m2[0].length,
+              });
+            }
+
+            break
+          case 2:
+            // escaped preformatted text
+            fragment.html += escape(verbatimText) + '\n';
+
+            break;
+          case 3:
+            // preformatted
+            fragment.html += verbatimText + '\n';
+
+            break;
+          case 4:
+            // directive block args
+            if (directive.def == null) break;
+            lastIndex = sniffTestRe.lastIndex;;
+            if (doc == null) {
+              if (typeof directive.def.meta === 'function') {
+                meta[directive.name] = directive.def.meta({
+                  inlineArgs: directive.inlineArgs,
+                  blockArgs: verbatimText,
+                });
+              }
+            } else if (typeof directive.def.render === 'function') {
+              try {
+                fragment.html += directive.def.render({
+                  doc,
+                  inlineArgs: directive.inlineArgs,
+                  blockArgs: verbatimText,
+                }) ?? '' + ' ';
+              } catch (err) {
+                console.error(`Error in calling directive ${directive.name}`)
+                console.error(err)
+              }
+            } else if (typeof directive.def.asyncRender === 'function') {
+              asyncCount++;
+              
+              // async rendering uses the #[ref] feature to insert the
+              // eventual response. 
+              const name = directive.name;
+              const directiveFragment = makeFragment('embed');
+
+              directiveFragment.id = `@${asyncCount}`;
+              parsed.set(directiveFragment.id, directiveFragment);
+
+              fragment.refs.push({
+                id: directiveFragment.id,
+                start: fragment.html.length,
+                end: fragment.html.length,
+              });
+
+              // in case text follows we want a space separating the render output
+              fragment.html += ' ';
+              
+              promises.push(
+                directive.def.asyncRender({
+                  doc,
+                  inlineArgs: directive.inlineArgs,
+                  blockArgs: verbatimText,
+                }).then(res => {
+                  directiveFragment.html = res ?? '';
+                }).catch(err => {
+                  console.error(`Error in calling directive ${name}`)
+                  console.error(err)
+                })
+              );
+            } else if (typeof directive.def.element === 'function') {
+              if (element.beforeRender == null) element.beforeRender = [];
+
+              element.beforeRender.push({
+                blockArgs: verbatimText,
+                inlineArgs: directive.inlineArgs,
+                element: directive.def.element,
+              });
+            } else {
+              console.warn(`Directive used in incorrect context ${directive.name}`);
+            }
+            sniffTestRe.lastIndex = lastIndex;
+        }
+
+        verbatimType = 0;
+        verbatimText = '';
+        applyIndent(indent, key, element, fragment, doc, parsed, output, args);
+
+        if (preformatClose.has(m1[0].trim())) continue;
+      }
+    }
+
+    if (m1[LINE].trim() === '') {
+      // empty lines have no effect from here on
+      continue;
+    }
+
+    if (doc === undefined) {
+      // The meta directives get special treatment.
+      // Parsers can use the head output type to output
+      // the meta results only.
+      let parseBlock = false, url: string;
+      const inlineArgs = m1[DIRECTIVE_INLINE_ARGS] ?? '';
+      
+      switch (m1[DIRECTIVE]) {
+        case 'id':
+          url = inlineArgs.trim();
+          parseBlock = true;
+
+          try {
+            id = id ?? new URL(url).toString();
+          } catch {
+            console.warn(
+              `Invalid URL given to @id directive: ${url}`
+            );
+          }
+          break;
+        case 'type':
+          parseBlock = true;
+          type = type ?? inlineArgs.trim();
+          break;
+        case 'lang':
+          parseBlock = true;
+          lang = lang ?? inlineArgs.trim();
+          break;
+        case 'dir':
+          parseBlock = true;
+          dir = dir ?? inlineArgs.trim();
+      }
+
+      // Even though the builtin meta directives do not support block args
+      // the args need to be parsed so they do not end up in the output.
+      const def = directives[m1[DIRECTIVE]];
+
+      if (typeof def?.meta === 'function'|| parseBlock) {
+        verbatimIndent = indent + 1;
+        verbatimType = 4;
+        directive = {
+          name: m1[DIRECTIVE],
+          inlineArgs,
+          def,
+        }
+
+        continue main;
+      }
+
+      if (output.outputMode === 'head') {
+        return {
+          key,
+          id,
+          lang,
+          dir,
+          meta,
+          data,
+        } as unknown as ParsedLongform;
+      }
+
+      doc = Object.freeze({ id, type, lang, dir, meta });
+    }
+
+    switch (m1[DIRECTIVE_KEY] ?? m1[ID_TYPE] ?? m1[ELEMENT] ?? m1[ATTR]) {
+      case '#':
+      case '##':
+        [element, fragment] = applyIndent(indent, key, element, fragment, doc, parsed, output, args);
+
+        fragment.id = m1[ID];
+
+        if (indent === 0) {
+          if (m1[FRAGMENT_TYPE] == '[') {
+            fragment.type = 'range';
+            } else if (m1[FRAGMENT_TYPE] === '"') {
+            fragment.type = 'text';
+          } else if (m1[ID_TYPE] === '##') {
+            fragment.type = 'bare';
+          } else {
+            fragment.type = 'embed';
+            element.id = fragment.id;
+          }
+        } else {
+          element.id = fragment.id;
+        }
+
+        break;
+      // deno-lint-ignore no-fallthrough
+      case '::': {
+        if (
+          element.tag !== undefined ||
+          element.indent > indent
+        ) {
+          [element, fragment] = applyIndent(indent, key, element, fragment, doc, parsed, output, args);
+        }
+
+        element.indent = indent;
+        
+        if (indent === 0 && fragment.id == null) {
+          if (root != null) {
+            // skip if root is found and this fragment
+            // has no id
+            skipping = true;
+          } else {
+            fragment.type = 'root';
+            root = fragment;
+          }
+        }
+        
+        // output mode templates parses fragments as though
+        // they were templates, including the root fragment
+        if (output.outputMode !== 'templates') {
+          let preformattedType: string | undefined;
+          let inlineText: string | undefined;
+
+          const parent = element;
+          outerRe.lastIndex = 0;
+
+          // Looping through chained element declarations
+          // foo#x.y::bar::free:: 
+          while ((m2 = outerRe.exec(m1[LINE]))) {
+            let working: WorkingElement;
+
+            preformattedType = m2[3];
+            inlineText = m2[4];
+
+            if (element.tag === undefined) {
+              element.tag = m2[1];
+              working = element;
+            } else {
+              if (parent.chain === undefined) parent.chain = [];
+              working = makeElement(indent);
+              working.tag = m2[1];
+              parent.chain.push(working);
+            }
+
+            innerRe.lastIndex = 0;
+            // Looping through ids, classes and attrs
+            while((m3 = innerRe.exec(m2[2]))) {
+              if (m3[2] !== undefined) {
+                working.id = m3[2];
+              } else if (m3[1] !== undefined) {
+                if (working.class == null) {
+                  working.class = m3[1];
+                } else {
+                  working.class += ' ' + m3[1];
+                }
+              } else {
+                // TODO: Preserve quoting style around attribute values
+                const value: string | boolean | undefined | null = m3[4] ?? m3[5] ?? m3[6];
+
+                handleAttribute(
+                  m3[3],
+                  value,
+                  working,
+                  doc,
+                  directives,
+                );
+              }
+            }
+          }
+
+          if (preformattedType === undefined && inlineText != null) {
+            m2 = attributeOrInlineDirectiveRe.exec(inlineText);
+
+            if (m2 != null) {
+              const name = m2[1];
+              const def = directives[name];
+
+              if (typeof def?.render === 'function') {
+                inlineText = def.render({ doc }) ?? '';
+              } else if (typeof def?.asyncRender === 'function') {
+                asyncCount++;
+                
+                // async rendering uses the #[ref] feature to insert the
+                // eventual response. 
+                const directiveFragment = makeFragment('embed');
+
+                directiveFragment.id = `@${asyncCount}`;
+                parsed.set(directiveFragment.id, directiveFragment);
+
+                fragment.refs.push({
+                  id: directiveFragment.id,
+                  start: fragment.html.length,
+                  end: fragment.html.length,
+                });
+
+                // in case text follows we want a space separating the render output
+                promises.push(
+                  def.asyncRender({
+                    doc,
+                  }).then(res => {
+                    directiveFragment.html = res ?? '';
+                  }).catch(err => {
+                    console.error(`Error in calling directive ${name}`)
+                    console.error(err)
+                  })
+                );
+              }
+            }
+          }
+
+          // this is a hack to get temp support of mounting
+          // working. In the future it will be moved to a 
+          // server specific process.
+          if (element.mount != null) {
+            const id = element.mount;
+            
+            [element, fragment] = applyIndent(indent + 1, key, element, fragment, doc, parsed, output, args);
+
+            if (fragment.mountPoints == null) fragment.mountPoints = [];
+            
+            fragment.mountPoints.push({
+              id,
+              part: fragment.html,
+            });
+
+            fragment.html = '';
+            [element, fragment] = applyIndent(indent, key, element, fragment, doc, parsed, output, args);
+            break;
+          }
+  
+          if (preformattedType !== undefined) {
+            if (element.tag !== undefined)
+              [element, fragment] = applyIndent(indent + 1, key, element, fragment, doc, parsed, output, args);
+
+            verbatimIndent = indent + 1;
+            verbatimType = preformattedType === '{{' ? 3 : 2
+          } else if (inlineText !== undefined) {
+            element.text = inlineText;
+          }
+
+          break;
+        }
+
+        // handle as directive if output mode is templates
+        // the templateLinesRe directive will need to re-process this
+        // line so we rewind the sniffTestRe last index for it to copy
+        sniffTestRe.lastIndex = sniffTestRe.lastIndex - m1[0].length;
+      }
+      case '@': {
+        if (element.tag !== undefined) {
+          [element, fragment] = applyIndent(indent, key, element, fragment, doc, parsed, output, args);
+        }
+
+        const inlineArgs = m1[DIRECTIVE_INLINE_ARGS] ?? ''
+
+        switch (m1[DIRECTIVE] ?? 'template') {
+          case 'template':
+            if (indent === 0) {
+              let indented = false;
+              fragment.template = true;
+
+              templateLinesRe.lastIndex = sniffTestRe.lastIndex;
+              while ((m2 = templateLinesRe.exec(input))) {
+                if (m2[1] == null && !indented && fragment.id == null) {
+                  m3 = idRe.exec(m2[0]);
+
+                  if (m3 != null) fragment.id = m3[3];
+
+                  fragment.html += m2[0];
+                } else if (m2[1] == null && indented) {
+                  sniffTestRe.lastIndex = templateLinesRe.lastIndex - m2[0].length;
+                  break;
+                } else {
+                  fragment.html += '\n' + m2[0];
+                  if (m2[1] != null) indented = true;
+                }
+              }
+
+              [element, fragment] = applyIndent(0, key, element, fragment, doc, parsed, output, args);
+            }
+
+            continue main;
+          case 'doctype':
+            fragment.html += `<!doctype ${(inlineArgs.trim() || 'html').trim()}>`;
+            break;
+          case 'xml':
+            fragment.html += `<?xml ${inlineArgs.trim() || 'version="1.0" encoding="UTF-8"'}?>`;
+            break;
+          case 'mount':
+            if (output.outputMode !== 'mountable') break;
+
+            if (inlineArgs === '') {
+              console.warn('Mount points must have a name');
+            } else if (fragment.type !== 'root') {
+              console.warn('Mounting is only allowed on a root element');
+            }
+
+            fragment.mountable = true;
+            element.mount = inlineArgs.trim();
+            break;
+        }
+
+        const def = directives[m1[DIRECTIVE]];
+        
+        // A directive may not be defined but we want to process
+        // any block args to keep the output valid. Builtin directives
+        // will be ignored unless they require block args.
+        verbatimIndent = indent + 1;
+        verbatimType = 4;
+        directive = {
+          name: m1[DIRECTIVE],
+          inlineArgs: m1[DIRECTIVE_INLINE_ARGS],
+          def,
+        };
+
+        break;
+      }
+      // deno-lint-ignore no-fallthrough
+      case '[': {
+        if (element?.tag != null) {
+          attributeRe.lastIndex = 0;
+          m2 = attributeRe.exec(m1[LINE]);
+
+          if (m2 != null && element.tag != null) {
+            handleAttribute(
+              m2[2],
+              m2[3],
+              element,
+              doc,
+              directives,
+            );
+
+            break;
+          }
+        }
+
+        // if the attribute is not valid fall through to text processing of the line
+      }
+      default:
+        if (element.tag !== undefined)
+          [element, fragment] = applyIndent(indent, key, element, fragment, doc, parsed, output, args);
+
+        verbatimText = m1[0].trim();
+        verbatimIndent = indent;
+        verbatimType = 1;
+    }
+  }
+
+  applyIndent(0, key, element, fragment, doc, parsed, output, args);
+
+  if (promises.length > 0) await Promise.all(promises);
+
+  if (root?.mountable) {
+    output.tail = root.html;
+    output.mountpoints = root.mountPoints ?? [];
+
+    return output;
+  }
+
+  const arr = Array.from(parsed.values());
+
+  for (let i = 0; i < parsed.size + 1; i++) {
+    let fragment: WorkingFragment;
+    
+    if (i === 0 && root == null) {
+      continue;
+    } else if (i === 0) {
+      fragment = root as WorkingFragment;
+    } else {
+      fragment = arr[i - 1];
+    }
+
+    if (fragment.refs == null || fragment.refs.length === 0) {
+      continue;
+    }
+
+    flatten(fragment, claimed, parsed);
+  }
+  
+  if (root?.html != null) {
+    if (root.template) {
+      output.template = root.html; 
+    } else {
+      output.root = root.html;
+
+      if (key != null) output.selector = `[data-${key}-root]`;
+    }
+  }
+
+  let f: WorkingFragment;
+  for (let i = 0, l = arr.length; i < l; i++) {
+    let selector: string = undefined as unknown as string;
+
+    f = arr[i];
+
+    if (f?.id == undefined ||
+      claimed.has(f.id as string)) {
+      continue;
+    }
+
+    if (key != null) {
+      switch (f.type) {
+        // deno-lint-ignore no-fallthrough
+        case 'embed':
+          if (args?.annotations === 'obscure') {
+            selector = `[id=${f.id}]`;
+            break;
+          }
+        case 'bare':
+        case 'range': selector = `[data-${key}=${f.id}]`;
+      }
+    }
+
+    output.fragments[f.id as string] = {
+      id: f.id as string,
+      selector,
+      type: f.type as 'embed' | 'bare' | 'range',
+      html: f.html,
+    };
+  }
+
+  output.key = key as string;
+  output.id = id;
+  output.type = type
+  output.lang = lang;
+  output.dir = dir;
+  output.meta = meta;
+  output.outputMode = outputMode;
+  output.targetType = targetType;
+
+  return output;
+}
+
+/**
+ * Processes a client side Longform template to HTML fragment string.
+ *
+ * @param fragment    - The fragment identifier.
+ * @param args        - A record of template arguments.
+ * @param getFragment - A function which returns an already processed fragment's HTML string.
+ * @returns The processed template.
+ */
+export async function processTemplate(
+  template: string,
+  args: Record<string, string | number>,
+  longformArgs?: LongformArgs,
+  getFragment?: (fragment: string) => string | undefined,
+): Promise<string | undefined> {
+  const processed = template.replace(templateRe, (_line, _structured, param, ref) => {
+    if (ref !== undefined && typeof getFragment === 'function') {
+      const fragment = getFragment(ref);
+
+      if (fragment == null) return '';
+
+      return fragment;
+    }
+    
+    return args[param] != null ? escape(args[param].toString()) : '';
+  });
+
+  return Object.values((await longform(processed, longformArgs)).fragments)[0]?.html ?? null;
+}
+
+function handleAttribute(
+  name: string,
+  value: string | boolean | null | undefined,
+  element: WorkingElement,
+  doc: Doc,
+  directives: Record<string, Directive>,
+): void {
+  let m: RegExpExecArray | null;
+
+  if (typeof value === 'string' && value[0] === '@') {
+    m = attributeOrInlineDirectiveRe.exec(value as string);
+    
+    if (m != null) {
+      const def = directives[m[1]];
+
+      if (def != null && typeof def.attr === 'function') {
+        value = def.attr({ doc, tag: element.tag as string });
+
+        if (!value || value == null) return;
+      } else {
+        return;
+      }
+    }
+  }
+
+  switch (name) {
+    case 'id':
+      if (!element.id && typeof value === 'string') {
+        element.id = value;
+      }
+      break;
+    case 'class':
+      if (!element.class && typeof value === 'string') {
+        element.class = value;
+      } else if (typeof value === 'string') {
+        element.class += ' ' + value;
+      }
+      break;
+    default:
+      if (value !== false && value != null) {
+        if (typeof element.attrs[name] === 'string' &&
+            typeof value === 'string') {
+          element.attrs[name] += ' ' + value;
+        } else if (typeof value === 'string') {
+          element.attrs[name] = value;
+        } else if (value === true && element.attrs[name] == null) {
+          element.attrs[name] = true;
+        }
+      }
+  }
+}
+
+/**
+ * Closes any current in progress element definition
+ * and creates a new working element.
+ */
+function applyIndent(
+  targetIndent: number,
+  key: string | undefined,
+  element: WorkingElement,
+  fragment: WorkingFragment,
+  doc: Doc,
+  parsed: Map<string, WorkingFragment>,
+  output: ParsedLongform,
+  args?: LongformArgs,
+): [element: WorkingElement, fragment: WorkingFragment] {
+
+  if (element.tag !== undefined) {
+    if (Array.isArray(element.beforeRender)) {
+      const el: Element = {
+        id: element.id,
+        tag: element.tag,
+        class: element.class,
+        attrs: element.attrs,
+      };
+      const chain: Element[] = [];
+
+      for (let i = 0, l = element.chain.length, el = element.chain[i]; i < l; i++) {
+        chain.push({
+          id: el.id,
+          tag: el.tag,
+          class: el.class,
+          attrs: el.attrs,
+        });
+      }
+
+      for (let i = 0, l = element.beforeRender.length, def = element.beforeRender[i]; i < l; i++) {
+        (def.element as (ctx: ElementCtx) => void)({
+          el,
+          chain,
+          doc,
+          inlineArgs: def.inlineArgs,
+          blockArgs: def.blockArgs,
+        });
+      }
+    }
+
+    const root = fragment.type === 'range'
+      ? targetIndent < 2
+      : fragment.html === ''
+    ;
+
+    fragment.html += `<${element.tag}`;
+
+    if (element.id !== undefined) {
+      fragment.html += ' id="' + element.id + '"';
+    }
+
+    if (element.class !== undefined) {
+      fragment.html += ' class="' + element.class + '"';
+    }
+
+    for (const attr of Object.entries(element.attrs)) {
+      if (attr[0] === 'id' || attr[0] === 'class') continue;
+      if (attr[1] == null) {
+        fragment.html += ' ' + attr[0]
+      } else {
+        fragment.html += ` ${attr[0]}="${attr[1]}"`;
+      }
+    }
+
+    if (key != null) {
+      
+      if (root) {
+        if (fragment.type === 'root') {
+          fragment.html += ` data-${key}-root`;
+        } else if (fragment.type === 'bare' || fragment.type === 'range') {
+          fragment.html += ` data-${key}="${fragment.id}"`;
+        } else if (fragment.type === 'embed' && args?.annotations === 'obscure') {
+          fragment.html += ` data-${key}="${fragment.id}"`;
+        }
+      }
+
+      if (element.mount !== undefined) {
+        fragment.html += ` data-${key}-mount="${element.mount}"`;
+      }
+    }
+
+    fragment.html += '>';
+
+    if (Array.isArray(element.chain)) {
+      let chained: WorkingElement;
+
+      for (let i = 0, l = element.chain.length; i < l; i++) {
+        chained = element.chain[i];
+
+        fragment.html += '<' + chained.tag;
+
+        if (chained.id !== undefined) {
+          fragment.html += ' id="' + chained.id + '"';
+        }
+
+        if (chained.class != undefined) {
+          fragment.html += ' class="' + chained.class + '"';
+        }
+
+        for (const attr of Object.entries(chained.attrs)) {
+          if (attr[1] === undefined) {
+            fragment.html += ' ' + attr[0]
+          } else {
+            fragment.html += ` ${attr[0]}="${attr[1]}"`;
+          }
+        }
+
+        fragment.html += '>';
+      }
+    }
+
+    if (!voids.has(element.tag as string) && element.text != null) {
+      fragment.html += element.text;
+    }
+
+    if (
+      !voids.has(element.tag as string)
+    ) {
+      fragment.els.push(element);
+    }
+  }
+
+  if (targetIndent <= element.indent) {
+    element = makeElement(targetIndent);
+
+    while (
+      fragment.els.length !== 0 && (
+        targetIndent == null ||
+        fragment.els[fragment.els.length - 1].indent !== targetIndent - 1
+      )
+    ) {
+      const element = fragment.els.pop() as WorkingElement;
+
+      if (Array.isArray(element.chain)) {
+        for (let i = 0, l = element.chain.length; i < l; i++) {
+          fragment.html += `</${element.chain[i].tag}>`;
+        }
+      }
+
+      fragment.html += `</${element?.tag}>`;
+    }
+
+    if (targetIndent === 0) {
+      if (fragment.type !== 'root') {
+        if (fragment.template) {
+          output.templates[fragment.id] = fragment.html;
+        } else {
+          parsed.set(fragment.id, fragment);
+        }
+      }
+
+      fragment = makeFragment();
+    }
+  } else {
+    element = makeElement(targetIndent)
+  }
+
+  return [element, fragment];
+}
+
+function flatten(
+  fragment: WorkingFragment,
+  claimed: Set<string>,
+  parsed: Map<string, WorkingFragment>,
+  locals: Set<string> = new Set(),
+): WorkingFragment {
+  let r: FragmentRef;
+  if (Array.isArray(fragment.refs)) {
+    for (let i = fragment.refs.length - 1; i > -1; i--) {
+      r = fragment.refs[i];
+
+      if (locals.has(r.id) || claimed.has(r.id) || !parsed.has(r.id)) {
+        // cannot use fragment here. Clear the reference marker
+        fragment.html = fragment.html.slice(0, r.start)
+          + fragment.html.slice(r.end)
+      } else {
+        locals.add(fragment.id);
+
+        const child = flatten(
+          parsed.get(r.id) as WorkingFragment,
+          claimed,
+          parsed,
+          locals,
+        );
+
+        fragment.html = fragment.html.slice(0, r.start)
+          + child.html
+          + fragment.html.slice(r.end);
+
+        if (child.type === 'embed') {
+          claimed.add(child.id)
+        }
+      }
+    }
+  }
+
+  // don't re-process the fragment
+  fragment.refs = undefined as unknown as FragmentRef[];
+
+  return fragment;
+}
+