@longform/async 0.0.29

package/lib/mod.ts

@@ -0,0 +1,3 @@
+
+export * from './types.ts';
+export { longform, processTemplate } from './longform.ts';

package/lib/types.ts

@@ -0,0 +1,671 @@
+
+/**
+ * @internal
+ */
+export type SanitizerElement = {
+  tag: string;
+  attrs: string[];
+};
+
+/**
+ * @internal
+ */
+export type SanitizerConfig = {
+  allowAll: boolean;
+  allowedAttributes: string[];
+  allowedElements: Record<string, SanitizerElement>;
+};
+
+/**
+ * @internal
+ */
+export type WorkingElement = {
+  indent: number;
+  key?: string;
+  id?: string;
+  tag: string;
+  class?: string;
+  attrs: Record<string, string | true>;
+  text?: string;
+  html: string;
+  mount?: string;
+  sanitizerConfig?: SanitizerConfig;
+  chain: WorkingElement[];
+  beforeRender?: AppliedDirective[];
+};
+
+/**
+ * @internal
+ */
+export type WorkingFragmentType =
+  | 'root'
+  | 'embed'
+  | 'bare'
+  | 'range'
+  | 'text'
+  | 'mount'
+  | 'template'
+;
+
+/**
+ * @internal
+ */
+export type FragmentRef = {
+  id: string;
+  start: number;
+  end: number;
+};
+
+/**
+ * @internal
+ */
+export type WorkingFragment = {
+  id: string;
+  template: boolean;
+  mountable: boolean;
+  type: WorkingFragmentType;
+  html: string;
+  refs: FragmentRef[];
+  els: WorkingElement[];
+  mountPoints?: MountPoint[];
+};
+
+/**
+ * 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 type FragmentType =
+  | 'embed'
+  | 'bare'
+  | 'range'
+  | 'text'
+;
+
+/**
+ * A fragment object.
+ */
+export 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;
+};
+
+/**
+ * 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 type MountPoint = {
+  /**
+   * The id of the mountpoint.
+   */
+  id: string;
+
+  /**
+   * The HTML output for this part.
+   */
+  part: string;
+};
+
+/**
+ * A doc object used to provide directives with meta information
+ * about the doc while it is being parsed.
+ */
+export 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.
+ */
+export type Element = {
+
+  /**
+   * 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>;
+};
+
+/**
+ * Context supplied to directives declared in the global directive.
+ */
+export type GlobalCtx = {
+
+  /**
+   * A doc object used to provide directives with meta information
+   * about the doc while it is being parsed.
+   */
+  doc: Doc;
+};
+
+/**
+ * Context supplied to meta directives.
+ */
+export type MetaCtx = {
+
+  /**
+   * The directive's inline args.
+   */
+  inlineArgs?: string;
+
+  /**
+   * The directive's block args.
+   */
+  blockArgs?: string;
+};
+
+/**
+ * Context supplied to element directives.
+ */
+export 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;
+
+  /**
+   * The elements that are chained to the target element.
+   */
+  chain: Element[];
+};
+
+/**
+ * Context supplied to attr directives
+ */
+export 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>;
+};
+
+/**
+ * Context supplied to render directives.
+ */
+export 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>;
+};
+
+/**
+ * Context supplied to async directives.
+ */
+export 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>;
+};
+
+
+/**
+ * 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 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;
+
+  /**
+   * The global hook is not implemented.
+   *
+   * @internal.
+   */
+  global?: (ctx: GlobalCtx) => void;
+
+  /**
+   * 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) => Promise<string | undefined>;
+};
+
+/**
+ * @internal
+ */
+export type AppliedDirective = {
+  inlineArgs?: string;
+  blockArgs?: string;
+  element?: (ctx: ElementCtx) => void;
+};
+
+/**
+ * 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 type Annotation =
+  | 'none'
+  | 'predictable'
+  | 'obscure'
+;
+
+/**
+ * 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 type OutputMode =
+  | 'doc'
+  | 'head'
+  | 'mountable'
+  | 'templates'
+;
+
+/**
+ * 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 type TargetType =
+  | 'text/html'
+  | 'application/xhtml+xml'
+  | 'application/xml'
+;
+
+/**
+ * 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 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.
+   */
+  //allowAll?: boolean;
+
+  /**
+   * Configures the sanitizer to allow the given set of attributes unless elements specify more.
+   */
+  //allowedAttributes?: string[];
+
+  /**
+   * Configures the sanitizer to allow the given set of elements and their attributes.
+   */
+  //allowedElements?: Array<string | SanitizerElement>;
+
+  /**
+   * 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>;
+};
+
+/**
+ * An object containing the parsed Longform result.
+ */
+export 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;
+};
+