@longform/longform 0.0.10 → 0.0.12

package/lib/longform.ts

@@ -69,7 +69,7 @@ function makeElement(indent: number = 0): WorkingElement {
     html: '',
     mount: undefined,
     serializerConfig: undefined,
-    chain: undefined,
+    chain: undefined as unknown as WorkingElement[],
     beforeRender: undefined,
   };
 }
@@ -90,13 +90,14 @@ class Doc {
   id?: string;
   lang?: string;
   dir?: string;
-  meta: Record<string, unknown> = {};
+  meta: Readonly<Record<string, unknown>>;
   #serializerConfig: SerializerConfig;
 
   constructor(
-    id?: string | undefined,
-    lang?: string | undefined,
-    dir?: string | undefined,
+    id: string | undefined,
+    lang: string | undefined,
+    dir: string | undefined,
+    meta: Record<string, unknown>,
     allowAll?: boolean | undefined,
     allowedAttributes?: string[] | undefined,
     allowedElements?: Array<string | SerializationElement>,
@@ -104,6 +105,7 @@ class Doc {
     this.id = id;
     this.lang = lang;
     this.dir = dir;
+    this.meta = Object.freeze(meta);
     this.#serializerConfig = {
       allowAll: allowAll ?? false,
       allowedAttributes: allowedAttributes ?? [],
@@ -162,20 +164,34 @@ export function longform(
     , fragment: WorkingFragment = makeFragment()
     // the root fragment
     , root: WorkingFragment | null = null
-    , id: string | undefined
-    , lang: string | undefined
-    , dir: string | undefined
+    , id: string | undefined = args?.id
+    , lang: string | undefined = args?.lang
+    , dir: string | undefined = args?.dir
+    , meta: Record<string, unknown> = {}
     , doc: Doc | undefined
     // ids of claimed fragments
   const claimed: Set<string> = new Set()
     // parsed fragments
-    , parsed: Map<string, WorkingFragment> = new Map()
+    , parsed: Map<string, WorkingFragment> = new Map(
+      Object.entries(args?.fragments as unknown as Record<string, WorkingFragment> ?? {})
+    )
     , output: ParsedResult = Object.create(null)
     , directives: Record<string, DirectiveDef> = {}
 
+  let key: string = args?.key as string;
 
-  output.fragments = Object.assign({}, args?.fragments);
-  output.templates = Object.create(null);
+  if (!args?.predictable && key == null) {
+    const arr = new Uint8Array(10);
+
+    crypto.getRandomValues(arr)
+
+    key = arr.toHex();
+  } else if (key == null) {
+    key = 'lf';
+  }
+
+  output.fragments = {};
+  output.templates = {};
 
   if (args?.directives != null) {
     const entries = Object.entries(args.directives);
@@ -199,7 +215,7 @@ export function longform(
     if (Array.isArray(element.beforeRender)) {
       const el: SimplifiedElement = {
         id: element.id,
-        tag: element.tag,
+        tag: element.tag as string,
         class: element.class,
         attrs: element.attrs,
       };
@@ -208,7 +224,7 @@ export function longform(
       for (let i = 0, l = element.chain.length, el = element.chain[i]; i < l; i++) {
         chain.push({
           id: el.id,
-          tag: el.tag,
+          tag: el.tag as string,
           class: el.class,
           attrs: el.attrs,
         });
@@ -218,7 +234,7 @@ export function longform(
         def.beforeRender({
           el,
           chain,
-          doc,
+          doc: doc as Doc,
           inlineArg: def.inlineArg,
           blockArg: def.blockArg,
         });
@@ -233,18 +249,6 @@ export function longform(
 
       fragment.html += `<${element.tag}`
 
-      if (root) {
-        if (fragment.type === 'root') {
-          fragment.html += ` data-lf-root`;
-        } else if (fragment.type === 'bare' || fragment.type === 'range') {
-          fragment.html += ` data-lf="${fragment.id}"`;
-        }
-      }
-
-      if (element.mount !== undefined) {
-        fragment.html += ` data-lf-mount="${element.mount}"`;
-      }
-
       if (element.id !== undefined) {
         fragment.html += ' id="' + element.id + '"';
       }
@@ -254,6 +258,7 @@ export function longform(
       }
 
       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 {
@@ -261,6 +266,20 @@ export function longform(
         }
       }
 
+      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?.predictable) {
+          fragment.html += ` data-${key}="${fragment.id}"`;
+        }
+      }
+
+      if (element.mount !== undefined) {
+        fragment.html += ` data-${key}-mount="${element.mount}"`;
+      }
+
       fragment.html += '>';
 
       if (Array.isArray(element.chain)) {
@@ -311,7 +330,7 @@ export function longform(
           fragment.els[fragment.els.length - 1].indent !== targetIndent - 1
         )
       ) {
-        const element = fragment.els.pop();
+        const element = fragment.els.pop() as WorkingElement;
 
         if (Array.isArray(element.chain)) {
           for (let i = 0, l = element.chain.length; i < l; i++) {
@@ -347,7 +366,7 @@ export function longform(
 
     // If this is a script tag or preformatted block
     // we want to retain the intended formatting less
-    // the indent. Preformatting can apply to any element
+    // the indent. Pre-formatting can apply to any element
     // by ending the declaration with `:: {`.
     if (verbatimIndent != null) {
       // inside a script or preformatted block
@@ -402,21 +421,45 @@ export function longform(
 
       switch (m1[DIRECTIVE]) {
         case 'id': {
-          // TODO: Add id validation
-          id = inlineArgs.trim();
+          id = id ?? new URL(inlineArgs.trim(), args?.base).toString();
           continue main;
         }
         case 'lang': {
-          lang = inlineArgs.trim();
+          lang = lang ?? inlineArgs.trim();
           continue main;
         }
         case 'dir': {
-          dir = inlineArgs.trim();
+          dir = dir ?? inlineArgs.trim();
           continue main;
         }
+        default: {
+          const def = directives[m1[DIRECTIVE]];
+
+          if (typeof def?.meta === 'function') {
+            if (Object.keys(def).length > 1) {
+              throw new Error(
+                `A custom directive performing the meta role cannot be used for other purposes. ` +
+                `See @${m1[DIRECTIVE]}`,
+              );
+            }
+
+            meta[m1[DIRECTIVE]] = def.meta({ inlineArgs });
+            continue main;
+          }
+        }
       }
 
-      doc = new Doc(id, lang, dir, args?.allowAll, args?.allowedAttributes, args?.allowedElements);
+      doc = new Doc(id, lang, dir, meta, args?.allowAll, args?.allowedAttributes, args?.allowedElements);
+
+      if (args?.outputMode === 'meta') {
+        return {
+          key,
+          id,
+          lang,
+          dir,
+          meta: doc.meta,
+        };
+      }
     }
 
     switch (m1[DIRECTIVE_KEY] ?? m1[ID_TYPE] ?? m1[ELEMENT] ?? m1[ATTR]) {
@@ -707,6 +750,8 @@ export function longform(
   const arr = Array.from(parsed.values());
 
   function flatten(fragment: WorkingFragment): WorkingFragment {
+    if (fragment.refs == null) fragment.refs = [];
+
     // work backwards so we don't change the html string length
     // for the later replacements
     for (let j = fragment.refs.length - 1; j >= 0; j--) {
@@ -747,7 +792,7 @@ export function longform(
     if (i === 0 && root == null) {
       continue;
     } else if (i === 0) {
-      fragment = root;
+      fragment = root as WorkingFragment;
     } else {
       fragment = arr[i - 1];
     }
@@ -761,41 +806,44 @@ export function longform(
 
   if (root?.html != null) {
     output.root = root.html;
-    output.selector = `[data-lf-root]`;
+    output.selector = `[data-${key}-root]`;
   }
 
   for (let i = 0; i < arr.length; i++) {
-    let selector: string;
-    const fragment = arr[i];
+    let selector!: string;
+    const fragment: WorkingFragment = arr[i];
 
-    if (fragment == null || claimed.has(fragment.id)) {
+    if (fragment == null || claimed.has(fragment.id as string)) {
       continue;
     }
 
-    if (fragment.type === 'embed') {
-      selector = `[id=${fragment.id}]`;
-    } else if (fragment.type === 'bare') {
-      selector = `[data-lf=${fragment.id}]`;
-    } else if (fragment.type === 'range') {
-      selector = `[data-lf=${fragment.id}]`;
+    switch (fragment.type) {
+      case 'embed': {
+        if (args?.predictable) {
+          selector = `[id=${fragment.id}]`;
+          break;
+        }
+      }
+      case 'bare':
+      case 'range': selector = `[data-${key}=${fragment.id}]`;
     }
 
-    output.fragments[fragment.id] = {
-      id: fragment.id,
+    output.fragments[fragment.id as string] = {
+      id: fragment.id as string,
       selector,
       type: fragment.type as 'embed' | 'bare' | 'range',
       html: fragment.html,
     };
   }
 
+  output.key = key;
   output.id = doc?.id;
   output.lang = doc?.lang;
+  output.dir = doc?.dir;
 
   return output;
 }
 
-
-
 /**
  * Processes a client side Longform template to HTML fragment string.
  *
@@ -823,3 +871,4 @@ export function processTemplate(
 
   return Object.values(longform(lf).fragments)[0]?.html ?? null;
 }
+

package/lib/types.ts

@@ -72,18 +72,6 @@ export type MountPoint = {
   part: string;
 };
 
-export type ParsedResult = {
-  id?: string;
-  lang?: string;
-  mountable?: boolean;
-  root?: string;
-  selector?: string;
-  mountPoints: MountPoint[];
-  tail?: string;
-  fragments: Record<string, Fragment>;
-  templates: Record<string, string>;
-};
-
 export type Doc = {
   id?: string;
   lang?: string;
@@ -105,6 +93,10 @@ export type GlobalCtx = {
   doc: Doc;
 };
 
+export type MetaCtx = {
+  inlineArgs?: string;
+}
+
 export type BeforeRenderCtx = {
   inlineArg?: string;
   blockArg?: string;
@@ -132,7 +124,13 @@ export type AppliesTo =
 ;
 
 export type DirectiveDef = {
-  onGlobal?: (ctx: GlobalCtx) => void;
+  /**
+   * A directive that implements the meta hook cannot be used for other purposes.
+   * This is enforced by the parser through checking the amount of keys on the
+   * definition object.
+   */
+  meta?: (args: MetaCtx) => unknown;
+  global?: (ctx: GlobalCtx) => void;
   beforeFragment?: () => void;
   beforeElement?: () => void;
   beforeRender?: (ctx: BeforeRenderCtx) => void;
@@ -151,11 +149,82 @@ export type AppliedDirective = {
   renderAttr?: (ctx: AttrValueCtx) => string;
 }
 
+export type OutputMode =
+  | 'doc'
+  | 'meta'
+  | 'mountable'
+;
+
 export type LongformArgs = {
+
+  /**
+   * The key used for creating data attributes.
+   * Defaults to a random string or 'lf' if predictable mode is enabled.
+   */
   key?: string;
+
+  /**
+   * If true the parser will default to using the 'lf' key for data attributes
+   * and fragments with embedded ids will not used data attributes for selectors.
+   *
+   * This is less safe in environments where Longform is used for SSR.
+   */
+  predictable?: boolean;
+
+  /**
+   * The id of the document. If set the @id is ignored.
+   * This can be used when creating partial re-usable documents.
+   */
+  id?: string;
+
+  /**
+   * The language tag of the document. If set the @lang
+   * directive is ignored.
+   * This can be used when creating partial re-usable documents.
+   */
+  lang?: string;
+  
+  /**
+   * The text direction of the document. If set the @dir
+   * directive is ignored.
+   * This can be used when creating partial re-usable documents.
+   */
+  dir?: string;
+
+  /**
+   * A base URL that can be used for resolving relative URLs
+   * declared using the @id directive.
+   */
+  base?: string;
+
+  /**
+   * Metadata set on the document.
+   */
+  meta?: Record<string, unknown>;
+
+  /**
+   * The output mode of the document.
+   */
+  outputMode?: OutputMode;
+
   allowAll?: boolean;
   allowedAttributes?: string[];
   allowedElements?: Array<string | SerializationElement>;
   directives?: Record<string, DirectiveDef>;
   fragments?: Record<string, Fragment>;
 };
+
+export type ParsedResult = {
+  key: string;
+  id?: string;
+  lang?: string;
+  dir?: string;
+  meta: Record<string, unknown>;
+  mountable?: boolean;
+  root?: string;
+  selector?: string;
+  mountPoints: MountPoint[];
+  tail?: string;
+  fragments: Record<string, Fragment>;
+  templates: Record<string, string>;
+};

package/package.json

@@ -4,7 +4,7 @@
   "author": "Matthew Quinn",
   "homepage": "https://github.com/occultist-dev/longform",
   "license": "MIT",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "keywords": [
     "HTML",
@@ -49,7 +49,7 @@
     "prettier": "^3.6.2",
     "rollup": "^4.60.2",
     "tslib": "^2.8.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vnu-jar": "^26.4.16"
   },
   "files": [