@longform/longform 0.0.7 → 0.0.9

package/lib/longform.ts

@@ -1,4 +1,4 @@
-import type { FragmentType, ParsedResult, WorkingElement, WorkingFragment } from "./types.ts";
+import type { AppliedDirective, DirectiveDef, FragmentType, LongformArgs, ParsedResult, SerializationElement, SerializerConfig, SimplifiedElement, WorkingElement, WorkingFragment } from "./types.ts";
 
 const LINE = 0
     , INDENT = 1
@@ -19,22 +19,19 @@ const sniffTestRe = /^((?:  )*)(?:(@)([a-z][a-z\-]*(?::[a-z][a-z\-]*)?)(?:(?:::
   // 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.
-  //, outer = /([a-z][\w\-]*(?::[a-z][\w\-]*)?)([^:]+)*::(?: (?:({{?)|(.*)))?/gi
   , outer = /([a-z][\w\-]*(?::[a-z][\w\-]*)?)((?:(?:[^:])|(?::(?!:)))*)::(?: (?:({{?)|(.*)))?/gi
-  //, outer = /([a-z][\w\-]*(?::[a-z][\w\-]*)?)(.+?(?=::))?(?: (?:({{?)|(.*)))?/gi
 
   // captures each id, class and attribute declaration in an element
   , inner = /(?:\.([a-z][\w\-]+)|#([a-z][\w\-]+)|\[([a-z][a-z\-]+(?::[a-z][a-z|\-]*)?)(?:=(?:"([^"]+)"|'([^']+)'|([^\]]+)))?\])/gi
   , attribute1 = /((?:\ \ )+)\[(\w[\w-]*(?::\w[\w-]*)?)(?:=([^\n]+))?\]/
   , preformattedClose = /[ \t]*}}?[ \t]*/
   , id1 = /((?:\ \ )+)?#(#)?([\w\-]+)(?: ([\["]))?/gmi
-  , idnt1 = /^(\ \ )+/
+  , identRe = /^(\ \ )+/
   , text1 = /^((?:\ \ )+)([^ \n][^\n]*)$/i
   , refRe = /#\[([\w\-]+)\]/g
   , escapeRe = /([&<>"'#\[\]{}])/g
   , templateLinesRe = /^(\ \ )?([^\n]+)$/gmi
-
-  // TODO: Benchmark v Array.includes()
+  , templateRe = /\#\{(@)?([a-z][\w\-]*(?::[a-z][\w\-]*))}/g
   , voids = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wrb']);
 
 let m1: RegExpExecArray | null
@@ -63,9 +60,17 @@ function escape(value: string): string {
 function makeElement(indent: number = 0): WorkingElement {
   return {
     indent,
-    html: '',
+    key: undefined,
+    id: undefined,
+    tag: undefined,
+    class: undefined,
+    text: undefined,
     attrs: {},
+    html: '',
+    mount: undefined,
+    serializerConfig: undefined,
     chain: undefined,
+    beforeRender: undefined,
   };
 }
 
@@ -81,14 +86,70 @@ function makeFragment(type: FragmentType = 'bare'): WorkingFragment {
   };
 }
 
+class Doc {
+  id?: string = undefined;
+  lang?: string = undefined;
+  meta: Record<string, unknown> = {};
+  #serializerConfig: SerializerConfig;
+
+  constructor(
+    id?: string | undefined,
+    lang?: string | undefined,
+    allowAll?: boolean | undefined,
+    allowedAttributes?: string[] | undefined,
+    allowedElements?: Array<string | SerializationElement>,
+  ) {
+    this.id = id;
+    this.lang = lang;
+    this.#serializerConfig = {
+      allowAll: allowAll ?? false,
+      allowedAttributes: allowedAttributes ?? [],
+      allowedElements: {},
+    };
+
+    if (allowedElements != null) {
+      for (let i = 0, l = allowedElements.length, el = allowedElements[i]; i < l; i++) {
+        if (typeof el === 'string') {
+          this.#serializerConfig.allowedElements[el] = {
+            tag: el,
+            attrs: [],
+          };
+        } else {
+          this.#serializerConfig.allowedElements[el.tag] = el;
+        }
+      }
+    }
+    
+    Object.freeze(this);
+  }
+
+  allowAll() {
+
+  }
+
+  allowAttributes() {
+
+  }
+
+  allowElements() {
+
+  }
+}
+
+const directiveValidator = /^[a-z][a-z\-]*\:[a-z][a-z\-]*$/gi;
+
+
 /**
  * Parses a longform document into a object containing the root and fragments
  * in the output format.
  *
- * @param {string} doc - The longform document to parse.
- * @returns {ParsedResult}
+ * @param input - The Longform document to parse.
+ * @param args - Arguments for the Longform parser.
  */
-export function longform(doc: string, debug: (...d: unknown[]) => void = () => {}): ParsedResult {
+export function longform(
+  input: string,
+  args?: LongformArgs,
+): ParsedResult {
   let skipping: boolean = false
     , textIndent: number | null = null
     , verbatimSerialize: boolean = true
@@ -98,20 +159,68 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
     , fragment: WorkingFragment = makeFragment()
     // the root fragment
     , root: WorkingFragment | null = null
+    , id: string | undefined
+    , lang: string | undefined
+    , doc: Doc | undefined
     // ids of claimed fragments
   const claimed: Set<string> = new Set()
     // parsed fragments
     , parsed: Map<string, WorkingFragment> = new Map()
-    , output: ParsedResult = Object.create(null);
+    , output: ParsedResult = Object.create(null)
+    , directives: Record<string, DirectiveDef> = {}
+
 
   output.fragments = Object.create(null);
   output.templates = Object.create(null);
+
+  if (args?.directives != null) {
+    const entries = Object.entries(args.directives);
+
+    for (let i = 0, l = entries.length; i < l; i++) {
+      if (!directiveValidator.test(entries[i][0])) {
+        console.warn(`Invalid custom directive name '${entries[i][0]}'`);
+
+        continue;
+      }
   
+      directives[entries[i][0]] = entries[i][1];
+    }
+  }
+
   /**
    * Closes any current in progress element definition
    * and creates a new working element.
    */
   function applyIndent(targetIndent: number) {
+    if (Array.isArray(element.beforeRender)) {
+      const el: SimplifiedElement = {
+        id: element.id,
+        tag: element.tag,
+        class: element.class,
+        attrs: element.attrs,
+      };
+      const chain: SimplifiedElement[] = [];
+
+      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.beforeRender({
+          el,
+          chain,
+          doc,
+          inlineArg: def.inlineArg,
+          blockArg: def.blockArg,
+        });
+      }
+    }
+
     if (element.tag != null) {
       const root = fragment.type === 'range'
         ? targetIndent < 2
@@ -210,7 +319,6 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
       }
 
       if (targetIndent === 0) {
-        debug(0, '<', fragment.type, fragment.id);
         if (fragment.template) {
           output.templates[fragment.id] = fragment.html;
         } else if (fragment.type === 'root') {
@@ -226,7 +334,7 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
     }
   }
 
-  while ((m1 = sniffTestRe.exec(doc))) {
+  main: while ((m1 = sniffTestRe.exec(input))) {
     if (m1[1] === '--') {
       continue;
     } else if (fragment.template) {
@@ -239,15 +347,14 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
     // by ending the declaration with `:: {`.
     if (verbatimIndent != null) {
       // inside a script or preformatted block
-      idnt1.lastIndex = 0;
-      m2 = idnt1.exec(m1[0]);
+      identRe.lastIndex = 0;
+      m2 = identRe.exec(m1[0]);
       const indent = m2 == null
         ? null
         : m2[0].length / 2;
 
       if (m2 == null || indent as number <= verbatimIndent) {
         fragment.html += '\n';
-        debug(indent, '}', m2?.[0]);
 
         applyIndent(indent);
         verbatimIndent = null;
@@ -259,7 +366,6 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
         }
       } else {
         const line = m1[0].replace('  '.repeat(verbatimIndent + 1), '');
-        debug(indent, '{', line);
 
         if (element.tag != null) {
           applyIndent(indent as number);
@@ -285,6 +391,26 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
       continue;
     }
 
+    // The id and lang directives should proceed all other directives and 
+    // fragment declarations.
+    if (doc === undefined) {
+      const inlineArgs = m1[DIRECTIVE_INLINE_ARGS] ?? '';
+
+      switch (m1[DIRECTIVE]) {
+        case 'id': {
+          // TODO: Add id validation
+          id = inlineArgs.trim();
+          continue main;
+        }
+        case 'lang': {
+          lang = inlineArgs.trim();
+          continue main;
+        }
+      }
+
+      doc = new Doc(id, lang, args?.allowAll, args?.allowedAttributes, args?.allowedElements);
+    }
+
     switch (m1[DIRECTIVE_KEY] ?? m1[ID_TYPE] ?? m1[ELEMENT] ?? m1[ATTR]) {
       case '#':
       case '##': {
@@ -339,7 +465,7 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
             fragment.template = indent === 0;
 
             templateLinesRe.lastIndex = sniffTestRe.lastIndex;
-            while ((m2 = templateLinesRe.exec(doc))) {
+            while ((m2 = templateLinesRe.exec(input))) {
               if (m2[1] == null && !indented && fragment.id == null) {
                 id1.lastIndex = 0;
                 m3 = id1.exec(m2[0]);
@@ -370,6 +496,27 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
             element.mount = m1[DIRECTIVE_INLINE_ARGS].trim();
             break;
           }
+          default: {
+            const def = directives[m1[DIRECTIVE]];
+
+            if (def == null) break;
+
+            if (typeof def.beforeRender === 'function') {
+              if (element.id != null) {
+                applyIndent(indent);
+              }
+
+              if (element.beforeRender == null) element.beforeRender = [];
+
+              // TODO: Parse block args
+              const applied: AppliedDirective = {
+                ...def,
+                inlineArg: m1[DIRECTIVE_INLINE_ARGS],
+              };
+
+              element.beforeRender.push(applied);
+            }
+          }
         }
 
         break;
@@ -492,8 +639,6 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
            : undefined;
 
         if (m2 != null && element.tag != null) {
-          debug('a', m2[2], m2[3]);
-
           if (m2[2] === 'id') {
             if (element.id == null) {
               element.id = m2[3].trim();
@@ -522,8 +667,6 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
         const indent = m2[1].length / 2;
         const tx = m2[2].trim();
 
-        debug(indent, 't', m2[2]);
-
         if (element.tag != null) {
           applyIndent(indent);
 
@@ -637,11 +780,13 @@ export function longform(doc: string, debug: (...d: unknown[]) => void = () => {
     };
   }
 
+  output.id = doc?.id;
+  output.lang = doc?.lang;
+
   return output;
 }
 
 
-const templateRe = /(?:#{([\w][\w\-_]*)})|(?:#\[([\w][\w\-_]+)\])/g;
 
 /**
  * Processes a client side Longform template to HTML fragment string.

package/lib/types.ts

@@ -1,4 +1,16 @@
 
+
+export type SerializationElement = {
+  tag: string;
+  attrs: string[];
+};
+
+export type SerializerConfig = {
+  allowAll: boolean;
+  allowedAttributes: string[];
+  allowedElements: Record<string, SerializationElement>;
+};
+
 export type WorkingElement = {
   indent: number;
   key?: string;
@@ -9,7 +21,9 @@ export type WorkingElement = {
   text?: string;
   html: string;
   mount?: string;
+  serializerConfig?: SerializerConfig;
   chain: WorkingElement[];
+  beforeRender?: AppliedDirective[];
 };
 
 export type WorkingFragmentType =
@@ -43,7 +57,7 @@ export type WorkingFragment = {
   html: string;
   refs: FragmentRef[];
   els: WorkingElement[];
-  mountPoints: MountPoint[];
+  mountPoints?: MountPoint[];
 };
 
 export type Fragment = {
@@ -59,6 +73,8 @@ export type MountPoint = {
 };
 
 export type ParsedResult = {
+  id?: string;
+  lang?: string;
   mountable?: boolean;
   root?: string;
   selector?: string;
@@ -68,3 +84,77 @@ export type ParsedResult = {
   templates: Record<string, string>;
 };
 
+export type Doc = {
+  id?: string;
+  lang?: string;
+  meta: Readonly<Record<string, unknown>>;
+  serializerConfig?: SerializerConfig;
+  allowAll(): void;
+  allowAttributes(attributes: string[]): void;
+  allowElements(elements: Record<string,  SerializationElement>): void;
+};
+
+export type SimplifiedElement = {
+  id?: string;
+  tag: string;
+  class?: string;
+  attrs: Record<string, string | boolean | null>;
+};
+
+export type GlobalCtx = {
+  doc: Doc;
+};
+
+export type BeforeRenderCtx = {
+  inlineArg?: string;
+  blockArg?: string;
+  el: SimplifiedElement;
+  chain: SimplifiedElement[];
+  doc: Readonly<Doc>;
+  //serializerConfig?: SerializerConfig;
+  //setMeta(key: string, value: unknown): void;
+  //allowAll(): void;
+  //allowAttributes(attributes: string[]): void;
+  //allowElements(elements: Record<string,  SerializationElement>): void;
+};
+
+export type AttrValueCtx = {
+  tag: string;
+  doc: Readonly<Doc>;
+  meta: Readonly<Record<string, string>>
+};
+
+export type AppliesTo =
+  | 'self'
+  | 'direct-descendants'
+  | 'children'
+  | 'all'
+;
+
+export type DirectiveDef = {
+  onGlobal?: (ctx: GlobalCtx) => void;
+  beforeFragment?: () => void;
+  beforeElement?: () => void;
+  beforeRender?: (ctx: BeforeRenderCtx) => void;
+  render?: (inlineArgs?: string, blockArgs?: string) => string;
+  renderAttr?: (ctx: AttrValueCtx) => string;
+};
+
+export type AppliedDirective = {
+  inlineArg?: string;
+  blockArg?: string;
+  onGlobal?: (ctx: GlobalCtx) => void;
+  beforeFragment?: () => void;
+  beforeElement?: () => void;
+  beforeRender?: (ctx: BeforeRenderCtx) => void;
+  render?: (inlineArgs?: string, blockArgs?: string) => string;
+  renderAttr?: (ctx: AttrValueCtx) => string;
+}
+
+export type LongformArgs = {
+  key?: string;
+  allowAll?: boolean;
+  allowedAttributes?: string[];
+  allowedElements?: Array<string | SerializationElement>;
+  directives?: Record<string, DirectiveDef>;
+};

package/package.json

@@ -4,10 +4,22 @@
   "author": "Matthew Quinn",
   "homepage": "https://github.com/occultist-dev/longform",
   "license": "MIT",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
-  "main": "dist/longform.js",
-  "types": "dist/mod.d.ts",
+  "keywords": [
+    "HTML",
+    "Fragments",
+    "Templating",
+    "Longform"
+  ],
+  "main": "./dist/longform.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/longform.js",
+      "require": "./dist/longform.cjs"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/occultist-dev/longform"
@@ -24,12 +36,6 @@
       "url": "https://github.com/occultist-dev/longform/blob/main/LICENSE"
     }
   ],
-  "keywords": [
-    "HTML",
-    "Fragments",
-    "Templating",
-    "Longform"
-  ],
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/commonmark": "^0.27.10",
@@ -37,14 +43,14 @@
     "@types/jsdom": "^27.0.0",
     "@types/node": "^24.8.1",
     "commonmark": "^0.31.2",
-    "dompurify": "^3.3.0",
+    "dompurify": "^3.4.1",
     "jsdom": "^27.0.1",
     "marked": "^16.4.1",
     "prettier": "^3.6.2",
-    "rollup": "^4.53.3",
+    "rollup": "^4.60.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "vnu-jar": "^24.10.17"
+    "vnu-jar": "^26.4.16"
   },
   "files": [
     "package.json",
@@ -56,7 +62,7 @@
   "scripts": {
     "build": "node build.ts",
     "bench": "deno bench --no-check --allow-read ./bench/longform.bench.ts",
-    "test": "node --test lib/longform.test.ts",
+    "test": "node --test test/**/*.test.ts",
     "serve": "node ./serve.ts"
   }
 }