@longform/async 0.0.29

package/dist/types.d.ts

@@ -0,0 +1,555 @@
+/**
+ * @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.
+     */
+    /**
+     * 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>;
+};
+/**
+ * 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;
+};