@longform/async 0.2.0 → 0.2.1

package/dist/mod.d.ts

@@ -1,2 +1,563 @@
-export * from './types.ts';
-export { longform, processTemplate } from './longform.ts';
+/**
+ * The annotation method sets how data attributes can be set on
+ * elements outputted by the Longform parser. This is used by clients
+ * when searching the DOM for server rendered fragments, or in
+ * editing situations.
+ *
+ * `predictable` should only be used in situations where untrusted
+ * user data is not being added to the response. All data attributes
+ * would be prefixed with the `data-lf-` prefix, unless a `key` is
+ * passed in via the parser args.
+ *
+ * The predictable mode does not annotate fragments using data
+ * attributes if they have a Longform identifier as their HTML id.
+ *
+ * `obscure` creates a key that is hard to guess in advance when
+ * the document is created on the server. This should work in
+ * situations where HTTP caching is involved if the full document
+ * is created in one pass before being cached, as any untrusted
+ * data would also be baked into the response at the time of the
+ * obscure key's generation.
+ *
+ * This approach to obscuring potential data-attribute conflicts is
+ * not fool proof. Do not use it in situations where part of a
+ * Longform document would be parsed and cached before passing into
+ * another document which includes untrusted user data. The first
+ * pass might cache the obscure key and allow users to mimic the
+ * response and define blocks of HTML that are picked by the client's
+ * DOM processing logic.
+ *
+ * @see [Longform's security considerations](https://longform.occultist.dev/#security-considerations)
+ */
+export declare type Annotation = 'none' | 'predictable' | 'obscure';
+
+/* Excluded from this release type: AppliedDirective */
+
+/**
+ * Context supplied to async directives.
+ */
+export declare type AsyncRenderCtx = {
+    /**
+     * The directive's inline args.
+     */
+    inlineArgs?: string;
+    /**
+     * The directive's block args.
+     */
+    blockArgs?: string;
+    /**
+     * A doc object used to provide directives with meta information
+     * about the doc while it is being parsed.
+     */
+    doc: Readonly<Doc>;
+};
+
+/**
+ * Context supplied to attr directives
+ */
+export declare type AttrCtx = {
+    /**
+     * The element's tag.
+     */
+    tag: string;
+    /**
+     * A doc object used to provide directives with meta information
+     * about the doc while it is being parsed.
+     */
+    doc: Readonly<Doc>;
+};
+
+/**
+ * Directive definition object. Directives can support multiple roles
+ * but some crate ambiguities and should not be used together. The
+ * parser will ignore the directive if it implements hooks for conflicting
+ * roles.
+ *
+ * A directive implementing `meta` cannot implement `element`.
+ * A directive implementing `element` cannot implement `render` or `asyncRender`.
+ * A directive implementing `render` cannot implement `asyncRender`.
+ */
+export declare type Directive = {
+    /**
+     * The meta directive hook defines a meta value. Meta values can be accessed
+     * from the `doc.meta` object in other directive hooks and from
+     * the parsed result of a Longform document via the exported `parsed.meta`
+     * object.
+     *
+     * Meta directives should be used at the start of a longform document.
+     * They will be ignored by the longform parser if defined after the
+     * `@global` directive, directives implementing the element hook, or
+     * fragment definitions.
+     */
+    meta?: (args: MetaCtx) => unknown;
+    /* Excluded from this release type: global */
+    /**
+     * The attr directive hook can be used to set a element's attribute.
+     * It is triggered before element hooks defined for the same element
+     * or element chain.
+     */
+    attr?: (ctx: AttrCtx) => string | boolean | undefined | null;
+    /**
+     * The element hook can be used to set attribute and data values
+     * on an element with more context about the element's definition.
+     */
+    element?: (ctx: ElementCtx) => void;
+    /**
+     * The render hook can output custom HTML at the location it is
+     * called.
+     */
+    render?: (ctx: RenderCtx) => string | undefined;
+    /**
+     * The async render hook can output custom HTML after an asynchronous
+     * operation at the location it is called.
+     */
+    asyncRender?: (ctx: AsyncRenderCtx) => string | undefined | Promise<string | undefined>;
+};
+
+/**
+ * A doc object used to provide directives with meta information
+ * about the doc while it is being parsed.
+ */
+export declare type Doc = {
+    /**
+     * The `@id` value of the document.
+     */
+    id?: string;
+    /**
+     * The `@type` value of the document.
+     */
+    type?: string;
+    /**
+     * The `@lang` value of the document.
+     */
+    lang?: string;
+    /**
+     * The `@dir` value of the document.
+     */
+    dir?: string;
+    /**
+     * An object containing all meta values defined for the document.
+     * Note that they will not have the directive's `@` character
+     * prefixing them. So the directive `@foo:bar` will have the
+     * key of `foo:bar` in the meta object.
+     */
+    meta: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * An element's description. Directives with access to elements
+ * should only apply changes to its `attrs` object. The `id` can
+ * be set via the `attrs` object if it does not already have a
+ * value, and classes can be appended to the `class` value via
+ * the `attrs` object.
+ *
+ * The element's tag cannot be changed.
+ */
+declare type Element_2 = {
+    /**
+     * The element's tag.
+     */
+    tag: string;
+    /**
+     * The element's id.
+     */
+    id?: string;
+    /**
+     * The element's class value.
+     */
+    class?: string;
+    /**
+     * An object containing the element's attributes.
+     */
+    attrs: Record<string, boolean | string>;
+};
+export { Element_2 as Element }
+
+/**
+ * Context supplied to element directives.
+ */
+export declare type ElementCtx = {
+    /**
+     * The directive's inline args.
+     */
+    inlineArgs?: string;
+    /**
+     * The directive's block args.
+     */
+    blockArgs?: string;
+    /**
+     * A doc object used to provide directives with meta information
+     * about the doc while it is being parsed.
+     */
+    doc: Readonly<Doc>;
+    /**
+     * The element which is the target of the directive.
+     */
+    el: Element_2;
+    /**
+     * The elements that are chained to the target element.
+     */
+    chain: Element_2[];
+};
+
+/**
+ * A fragment object.
+ */
+export declare type Fragment = {
+    /**
+     * The Longform identifier for the element.
+     */
+    id: string;
+    /**
+     * A selector which can be used to extract the fragment from a pages DOM
+     * if the fragment had been server rendered.
+     */
+    selector: string;
+    /**
+     * The fragment type.
+     *
+     * `embed` indicates the fragment has a unique embedded HTML id.
+     * `bare` indicates the fragment has no embedded HTML id.
+     * `range` indicates the fragment is a range of elements, instead of having a single top level element.
+     * `text` indicates the fragment is text only can can be used in situations where HTML might be invalid.
+     */
+    type: FragmentType;
+    /**
+     * The fragment output as a string.
+     */
+    html: string;
+};
+
+/* Excluded from this release type: FragmentRef */
+
+/**
+ * The fragment type.
+ *
+ * `embed` indicates the fragment has a unique embedded HTML id.
+ * `bare` indicates the fragment has no embedded HTML id.
+ * `range` indicates the fragment is a range of elements, instead of having a single top level element.
+ * `text` indicates the fragment is text only can can be used in situations where HTML might be invalid.
+ */
+export declare type FragmentType = 'embed' | 'bare' | 'range' | 'text';
+
+/**
+ * Context supplied to directives declared in the global directive.
+ */
+export declare type GlobalCtx = {
+    /**
+     * A doc object used to provide directives with meta information
+     * about the doc while it is being parsed.
+     */
+    doc: Doc;
+};
+
+/**
+ * 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 declare function longform(input: string, args?: LongformArgs): Promise<ParsedLongform>;
+
+/**
+ * The Longform parser is designed to serve multiple roles.
+ *
+ *
+ * In a situation where a document containing a HTML page's main content
+ * is split from a re-useable layout the `'doc'` output mode can be used
+ * on the main content and the result passed as arguments to the Longform
+ * parser when parsing the layout document. The id, type, lang and direction
+ * as well as any custom meta values and the parsed fragments from the
+ * main document will be available to the template's fragments.
+ *
+ *
+ * In a situation where a directive is being defined, the output mode
+ * `head` can be used to use the Longform parser as a DSL for custom
+ * directives. The `templates` output mode can be used to parse the
+ * block arguments of the directive as Longform templates, with the
+ * directive supplying arguments specified by the directive.
+ *
+ *
+ * The `mountable` output mode is used where Longform needs to be outputted
+ * so another libraries SSR rendered content can fill the gaps in mountable
+ * elements. Usually this would be used for a layout document which is
+ * used in a similar way to Astro's islands.
+ */
+export declare type LongformArgs = {
+    /**
+     * The key used for creating data attributes.
+     * Defaults to a random string or 'lf' if predictable mode is enabled.
+     */
+    key?: string;
+    /**
+     * The id of the document. If set the `@id` is ignored.
+     * This can be used when creating partial re-usable documents.
+     */
+    id?: string;
+    /**
+     * The media type of the document. If set the `@type` directive within
+     * the input document is ignored.
+     */
+    type?: 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;
+    /**
+     * Metadata set on the document.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * The media type of the target document. This is used to control
+     * the output of the serialized markup. If `'text/html'` is given
+     * void elements will be formatted in the HTML style and attributes
+     * will not use quotes unless used in the input markup.
+     *
+     * XML target types will always have attributes wrapped in double
+     * quotes.
+     */
+    targetType?: TargetType;
+    /**
+     * The output mode of the document.
+     */
+    outputMode?: OutputMode;
+    /**
+     * Style in which data attributes are added to output HTML markup.
+     *
+     * This is used in SSR situations where a client will need to use the
+     * data attributes that annotate Longform rendered fragments and elements
+     * to rebuild the Longform document from client produced DOM.
+     */
+    annotations?: Annotation;
+    /**
+     * Configures the sanitizer to allow all elements and attributes in the document.
+     */
+    /**
+     * Configures the sanitizer to allow the given set of attributes unless elements specify more.
+     */
+    /**
+     * Configures the sanitizer to allow the given set of elements and their attributes.
+     */
+    /**
+     * Object of custom directives.
+     */
+    directives?: Record<string, Directive>;
+    /**
+     * Object of fragments to make available to the parser when processing fragment refs.
+     */
+    fragments?: Record<string, Fragment>;
+};
+
+/**
+ * Context supplied to meta directives.
+ */
+export declare type MetaCtx = {
+    /**
+     * The directive's inline args.
+     */
+    inlineArgs?: string;
+    /**
+     * The directive's block args.
+     */
+    blockArgs?: string;
+};
+
+/**
+ * If the parser's output mode is `mountable`, the Longform parser will
+ * break output of the root element up in locations where the `@mount:: mountPointId`
+ * directive is used.
+ */
+export declare type MountPoint = {
+    /**
+     * The id of the mountpoint.
+     */
+    id: string;
+    /**
+     * The HTML output for this part.
+     */
+    part: string;
+};
+
+/**
+ * The Longform parser supports several output modes which are
+ * useful for different situations.
+ *
+ * `doc` Outputs all fragments normally.
+ *
+ * `head` Parses the `\@id`, `\@type`, `\@lang`, `\@dir` and any directives
+ * implementing the `meta` directive hook. It exits as soon as it hits
+ * another directive type or fragment declaration.
+ *
+ * `mountable` Supports use of the `\@mount` directive for turning elements
+ * into mountpoints. This output mode populates the `mountpoints` array
+ * in the parse result. This array can be looped over and data from another
+ * rendering tool can mount its output into the named mount points. Once all
+ * mountpoint entries have been populated the `tail` property in the parsed
+ * result should be appended to the final document.
+ *
+ * The mountable mode is currently very basic in implementation and only
+ * supports documents implementing a single root element.
+ *
+ * `templates` parses every fragment as though it was a template even
+ * if the `\@template` directive is not used. This is useful for creating
+ * directives which use the block args to define a Longform template.
+ */
+export declare type OutputMode = 'doc' | 'head' | 'mountable' | 'templates';
+
+/**
+ * An object containing the parsed Longform result.
+ */
+export declare type ParsedLongform = {
+    /**
+     * The key used when annotating the markup with data attributes.
+     */
+    key?: string;
+    /**
+     * The id, or URL of the document.
+     */
+    id?: string;
+    /**
+     * The media type of the Longform document.
+     */
+    type?: string;
+    /**
+     * The language tag of the document.
+     */
+    lang?: string;
+    /**
+     * The text direction of the document.
+     */
+    dir?: string;
+    /**
+     * Meta values defined in the document's head.
+     */
+    meta: Record<string, unknown>;
+    /**
+     * The media type of the target document.
+     */
+    targetType?: TargetType;
+    /**
+     * The output mode used when parsing the document.
+     */
+    outputMode: OutputMode;
+    /**
+     * Style in which data attributes are added to output HTML markup.
+     */
+    annotations?: Annotation;
+    /**
+     * The root HTML output for the document.
+     */
+    root?: string;
+    /**
+     * The root block as a template.
+     * This is only produced if using the output mode of `'templates'`.
+     */
+    template?: string;
+    /**
+     * The root selector.
+     */
+    selector?: string;
+    /**
+     * The HTML fragments.
+     */
+    fragments: Record<string, Fragment>;
+    /**
+     * All parsed templates.
+     */
+    templates: Record<string, string>;
+    /**
+     * Document mount points.
+     */
+    mountpoints?: MountPoint[];
+    /**
+     * Final document part after mount points.
+     */
+    tail?: string;
+};
+
+/**
+ * Processes a client side Longform template to HTML fragment string.
+ *
+ * @param fragment - The fragment template.
+ * @param args - Args for the template.
+ * @param longformArgs - Args for the Longform parser.
+ * @param getFragment - A function which returns an already processed fragment's HTML string.
+ *
+ * @returns The processed template.
+ */
+export declare function processTemplate(template: string, args: Record<string, string | number>, longformArgs?: LongformArgs, getFragment?: (fragment: string) => string | undefined): Promise<TemplateOutput | undefined>;
+
+/**
+ * Context supplied to render directives.
+ */
+export declare type RenderCtx = {
+    /**
+     * The directive's inline args.
+     */
+    inlineArgs?: string;
+    /**
+     * The directive's block args.
+     */
+    blockArgs?: string;
+    /**
+     * A doc object used to provide directives with meta information
+     * about the doc while it is being parsed.
+     */
+    doc: Readonly<Doc>;
+};
+
+/* Excluded from this release type: SanitizerConfig */
+
+/* Excluded from this release type: SanitizerElement */
+
+/**
+ * The content type of the response can be passed into the Longform
+ * parser to change the shape of the output. The default value `text/html`
+ * will use HTML's method for closing void tags. The XML versions would
+ * use XML valid syntax.
+ *
+ * If `application/xml` is provided, no data attributes will be added to
+ * the outputted markup, even if an annotation mode or key is given.
+ */
+export declare type TargetType = 'text/html' | 'application/xhtml+xml' | 'application/xml';
+
+/**
+ * An object containing a parsed Longform template.
+ */
+export declare type TemplateOutput = {
+    /**
+     * The Longform identifier for the element.
+     */
+    id?: string;
+    /**
+     * The fragment type.
+     *
+     * `root` indicates the template is a root fragments
+     * `embed` indicates the fragment has a unique embedded HTML id.
+     * `bare` indicates the fragment has no embedded HTML id.
+     * `range` indicates the fragment is a range of elements, instead of having a single top level element.
+     * `text` indicates the fragment is text only can can be used in situations where HTML might be invalid.
+     */
+    type: 'root' | FragmentType;
+    /**
+     * The fragment output as a string.
+     */
+    html: string;
+};
+
+/* Excluded from this release type: WorkingElement */
+
+/* Excluded from this release type: WorkingFragment */
+
+/* Excluded from this release type: WorkingFragmentType */
+
+export { }

package/dist/types.d.ts

@@ -53,7 +53,7 @@ export type WorkingFragment = {
     html: string;
     refs: FragmentRef[];
     els: WorkingElement[];
-    mountPoints?: MountPoint[];
+    mountpoints?: MountPoint[];
 };
 /**
  * The fragment type.
@@ -287,7 +287,7 @@ export type Directive = {
     /**
      * The global hook is not implemented.
      *
-     * @internal.
+     * @internal
      */
     global?: (ctx: GlobalCtx) => void;
     /**
@@ -358,12 +358,12 @@ export type Annotation = 'none' | 'predictable' | 'obscure';
  *
  * `doc` Outputs all fragments normally.
  *
- * `head` Parses the `@id`, `@type`, @lang`, `@dir` and any directives
+ * `head` Parses the `\@id`, `\@type`, `\@lang`, `\@dir` and any directives
  * implementing the `meta` directive hook. It exits as soon as it hits
  * another directive type or fragment declaration.
  *
- * `mountable` Supports use of the `@mount` directive for turning elements
- * into mountpoints. This output mode populates the `mountPoints` array
+ * `mountable` Supports use of the `\@mount` directive for turning elements
+ * into mountpoints. This output mode populates the `mountpoints` array
  * in the parse result. This array can be looped over and data from another
  * rendering tool can mount its output into the named mount points. Once all
  * mountpoint entries have been populated the `tail` property in the parsed
@@ -373,7 +373,7 @@ export type Annotation = 'none' | 'predictable' | 'obscure';
  * supports documents implementing a single root element.
  *
  * `templates` parses every fragment as though it was a template even
- * if the `@template` directive is not used. This is useful for creating
+ * if the `\@template` directive is not used. This is useful for creating
  * directives which use the block args to define a Longform template.
  */
 export type OutputMode = 'doc' | 'head' | 'mountable' | 'templates';

package/lib/longform.ts

@@ -77,7 +77,7 @@ function makeFragment(type: FragmentType = 'bare'): WorkingFragment {
     mountable: false,
     els: [],
     refs: [],
-    mountPoints: [],
+    mountpoints: [],
   };
 }
 
@@ -550,9 +550,9 @@ export async function longform(
             
             [element, fragment] = applyIndent(indent + 1, key, element, fragment, doc, parsed, output, args);
 
-            if (fragment.mountPoints == null) fragment.mountPoints = [];
+            if (fragment.mountpoints == null) fragment.mountpoints = [];
             
-            fragment.mountPoints.push({
+            fragment.mountpoints.push({
               id,
               part: fragment.html,
             });
@@ -686,7 +686,7 @@ export async function longform(
 
   if (root?.mountable) {
     output.tail = root.html;
-    output.mountpoints = root.mountPoints ?? [];
+    output.mountpoints = root.mountpoints ?? [];
 
     return output;
   }
@@ -768,9 +768,9 @@ export async function longform(
 /**
  * Processes a client side Longform template to HTML fragment string.
  *
- * @param fragment The fragment template.
- * @param args Args for the template.
- * @param longformArgs Args for the Longform parser.
+ * @param fragment - The fragment template.
+ * @param args - Args for the template.
+ * @param longformArgs - Args for the Longform parser.
  * @param getFragment - A function which returns an already processed fragment's HTML string.
  * 
  * @returns The processed template.

package/lib/types.ts

@@ -67,7 +67,7 @@ export type WorkingFragment = {
   html: string;
   refs: FragmentRef[];
   els: WorkingElement[];
-  mountPoints?: MountPoint[];
+  mountpoints?: MountPoint[];
 };
 
 /**
@@ -346,7 +346,7 @@ export type Directive = {
   /**
    * The global hook is not implemented.
    *
-   * @internal.
+   * @internal
    */
   global?: (ctx: GlobalCtx) => void;
 
@@ -428,12 +428,12 @@ export type Annotation =
  *
  * `doc` Outputs all fragments normally.
  *
- * `head` Parses the `@id`, `@type`, @lang`, `@dir` and any directives
+ * `head` Parses the `\@id`, `\@type`, `\@lang`, `\@dir` and any directives
  * implementing the `meta` directive hook. It exits as soon as it hits
  * another directive type or fragment declaration.
  *
- * `mountable` Supports use of the `@mount` directive for turning elements
- * into mountpoints. This output mode populates the `mountPoints` array
+ * `mountable` Supports use of the `\@mount` directive for turning elements
+ * into mountpoints. This output mode populates the `mountpoints` array
  * in the parse result. This array can be looped over and data from another
  * rendering tool can mount its output into the named mount points. Once all
  * mountpoint entries have been populated the `tail` property in the parsed
@@ -443,7 +443,7 @@ export type Annotation =
  * supports documents implementing a single root element.
  *
  * `templates` parses every fragment as though it was a template even
- * if the `@template` directive is not used. This is useful for creating
+ * if the `\@template` directive is not used. This is useful for creating
  * directives which use the block args to define a Longform template.
  */
 export type OutputMode =