@openleaf-editor/element 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -2,9 +2,20 @@
 
 The `<openleaf-editor>` custom element: OpenLeaf's drop-in for CMS forms. HTML in, HTML out, syncs to a textarea.
 
-This is a **beta** (`0.1.0-beta.1`). APIs may still change. It has not been
+This is a **beta** (`0.1.0-beta.2`). APIs may still change. It has not been
 used in production, and it has not been driven by a real screen reader.
 
+> **Editor output is untrusted input.** Whatever the editor produces — and
+> whatever a user pasted into it — must be sanitized **on your server** before it
+> is stored or rendered as HTML. Client-side sanitization is a user-experience
+> feature, not a security control: anything the editor strips can be put back
+> with developer tools, because the editor runs under the user's control.
+>
+> [`@openleaf-editor/sanitize`](https://github.com/PeytonNowlin/openleaf/tree/main/packages/sanitize) ships the
+> canonical allowlist as data and generates configuration for DOMPurify, Python
+> `bleach` and PHP HTMLPurifier from it, so client and server enforce the same
+> rules. Read [SECURITY.md](https://github.com/PeytonNowlin/openleaf/blob/main/SECURITY.md) before you ship.
+
 ## Install
 
 ```bash
@@ -31,7 +42,9 @@ npm install @openleaf-editor/plugins-table@beta \
             @openleaf-editor/plugins-colour@beta \
             @openleaf-editor/plugins-highlight@beta \
             @openleaf-editor/plugins-import@beta \
-            @openleaf-editor/plugins-import-docx@beta
+            @openleaf-editor/plugins-import-docx@beta \
+            @openleaf-editor/plugins-session@beta \
+            @openleaf-editor/plugins-insert@beta
 ```
 
 ```ts
@@ -40,12 +53,16 @@ import { installColourPicker } from '@openleaf-editor/plugins-colour'
 import { installSyntaxHighlighting } from '@openleaf-editor/plugins-highlight'
 import { installImport } from '@openleaf-editor/plugins-import'
 import { installDocxImport } from '@openleaf-editor/plugins-import-docx'
+import { installSessionTools } from '@openleaf-editor/plugins-session'
+import { installInsertTools } from '@openleaf-editor/plugins-insert'
 
 installTableEditing()
 installColourPicker()
 installSyntaxHighlighting()
 installImport()
 installDocxImport()
+installSessionTools()
+installInsertTools()
 ```
 
 **Keep every `@openleaf-editor/*` package on the same version.** They pin each
@@ -81,6 +98,44 @@ Whatever that function throws is shown to the author verbatim, so write the
 message for them. For one editor with its own endpoint, set
 `element.imageUploader` instead.
 
-Sanitize submitted HTML on the server. `@openleaf-editor/sanitize` ships the same allowlist as data — including the narrow `style` allowance that alignment and colour need. If you sanitize with DOMPurify, install `styleAttributeHook` as well; the config alone cannot filter CSS per element.
+## Sanitizing submitted HTML
+
+Sanitize on the server — see the note at the top of this file for why.
+`@openleaf-editor/sanitize` ships the same allowlist as data, including the
+narrow `style` allowance that alignment and colour need.
+
+With DOMPurify, this is the whole setup:
+
+```js
+import DOMPurify from 'dompurify'
+import { configureDOMPurify, DEFAULT_POLICY } from '@openleaf-editor/sanitize'
+
+const purify = DOMPurify(window)
+const config = configureDOMPurify(purify, DEFAULT_POLICY)
+const clean = purify.sanitize(dirty, config)
+```
 
-See the [project README](https://github.com/PeytonNowlin/openleaf) for the rest.
+One call, because the safe setup has to be atomic. `configureDOMPurify` installs
+**both** hooks the policy needs and then returns a config that enables the
+features they guard:
+
+- `styleAttributeHook`, because `ALLOWED_ATTR` is global and DOMPurify filters no
+  CSS properties of its own — without it, permitting `style` permits
+  `position:fixed;inset:0`, a page-covering overlay that looks like your own UI.
+- `embedHook`, because the policy allows an `<iframe>` only when its `src` is on a
+  closed list of player hosts, which no DOMPurify config can express. Enabling
+  iframes without it would let `<iframe src="https://evil.example">` through the
+  sanitizer this file recommends.
+
+Reach for the individual hooks or `toDOMPurifyConfig` only if you manage
+DOMPurify hooks yourself. Both fail closed — they drop styles and iframes rather
+than trusting them — so the failure mode of getting it wrong is content loss
+rather than XSS. That is the right direction, and it is still worth not doing.
+
+## More
+
+- [API reference](https://github.com/PeytonNowlin/openleaf/blob/main/docs/api-reference.md) —
+  every attribute, property and `openleaf:*` event.
+- [SECURITY.md](https://github.com/PeytonNowlin/openleaf/blob/main/SECURITY.md) —
+  the threat model and a baseline CSP.
+- [Project README](https://github.com/PeytonNowlin/openleaf) for the rest.

package/dist/form-bridge.d.ts

@@ -0,0 +1,46 @@
+/** Owns the custom element's textarea and form-submission contract. */
+export declare class FormBridge {
+    #private;
+    private readonly host;
+    private readonly readValue;
+    private readonly writeValue;
+    constructor(host: HTMLElement, readValue: () => string, writeValue: (html: string) => void);
+    get textarea(): HTMLTextAreaElement | null;
+    bind(): HTMLTextAreaElement | null;
+    attach(): void;
+    detach(): void;
+    rebind(): void;
+    /**
+     * Write the document into the textarea.
+     *
+     * `value` is an optional already-serialized copy. The keystroke path has one
+     * in hand -- it is about to put the same string in the change event's detail
+     * -- and serializing the document twice per keystroke was measurable on a
+     * large post.
+     *
+     * An explicit sync also cancels a pending debounced one and clears the dirty
+     * flag: the write it was going to make has just happened.
+     */
+    sync(value?: string): void;
+    /**
+     * Record that the document changed, without serializing it.
+     *
+     * The serialization is what costs -- a `DOMSerializer` pass over the whole
+     * document and a ~0.33 MB string per keystroke on a 100-page document -- and
+     * nothing reads the result until one of the flush points below. So the change
+     * is only noted here, and the trailing timer exists for hosts that watch the
+     * textarea rather than the element.
+     */
+    markDirty(): void;
+    /**
+     * Write the document to the textarea if, and only if, it would differ.
+     *
+     * Two ways it can: the document changed since the last write, or something
+     * outside wrote to the textarea itself -- a script, a server re-render, a
+     * test. The second is why this cannot be a bare dirty check. Comparing
+     * against the string last written costs a string compare and no
+     * serialization, so the flush points stay free when nothing has moved.
+     */
+    flush(): void;
+}
+//# sourceMappingURL=form-bridge.d.ts.map

package/dist/form-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-bridge.d.ts","sourceRoot":"","sources":["../src/form-bridge.ts"],"names":[],"mappings":"AAYA,uEAAuE;AACvE,qBAAa,UAAU;;IASnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAFV,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,MAAM,EACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAGrD,IAAI,QAAQ,IAAI,mBAAmB,GAAG,IAAI,CAEzC;IAED,IAAI,IAAI,mBAAmB,GAAG,IAAI;IAmBlC,MAAM,IAAI,IAAI;IAmBd,MAAM,IAAI,IAAI;IAWd,MAAM,IAAI,IAAI;IAMd;;;;;;;;;;OAUG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAS1B;;;;;;;;OAQG;IACH,SAAS,IAAI,IAAI;IAUjB;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;CA0Bd"}

package/dist/form-bridge.js

@@ -0,0 +1,158 @@
+/**
+ * How long a document change may sit unwritten before the textarea catches up.
+ *
+ * Nothing reads the textarea between edits -- `submit` and `formdata` both
+ * force a write first, and so does teardown -- so this exists only for a host
+ * that watches the textarea itself, with a MutationObserver or a polling
+ * autosave. Writing on every keystroke instead cost a full re-serialization of
+ * the document per character: 12 ms on a plain 100-page document, 74 ms with
+ * tables, against a 16.7 ms frame.
+ */
+const SYNC_DELAY_MS = 300;
+/** Owns the custom element's textarea and form-submission contract. */
+export class FormBridge {
+    host;
+    readValue;
+    writeValue;
+    #textarea = null;
+    #form = null;
+    #dirty = false;
+    /** The last string this bridge wrote, so a foreign write is detectable. */
+    #written = null;
+    #timer = null;
+    constructor(host, readValue, writeValue) {
+        this.host = host;
+        this.readValue = readValue;
+        this.writeValue = writeValue;
+    }
+    get textarea() {
+        return this.#textarea;
+    }
+    bind() {
+        const id = this.host.getAttribute('for');
+        if (id) {
+            const root = this.host.getRootNode();
+            const element = root.getElementById?.(id);
+            if (element instanceof HTMLTextAreaElement)
+                this.#textarea = element;
+            else {
+                this.#textarea = null;
+                console.error(`<openleaf-editor for="${id}">: no <textarea id="${id}"> found. ` +
+                    'Content will not be submitted with the form.');
+            }
+            return this.#textarea;
+        }
+        this.#textarea = this.host.querySelector('textarea');
+        return this.#textarea;
+    }
+    attach() {
+        this.detach();
+        // Re-resolve a `for=` binding that could not be resolved at build time. A
+        // wrapper builds the element while it is still detached, and a detached
+        // root has no `getElementById`, so `bind()` found nothing and every later
+        // write went nowhere -- the editor looked right and the textarea it posts
+        // still held the server's original HTML.
+        //
+        // Safe here in a way `rebind()` is not: this only re-runs for an explicit
+        // `for`, whose id lookup is unambiguous, where the nested
+        // `querySelector('textarea')` can match the source box instead.
+        if (!this.#textarea && this.host.getAttribute('for'))
+            this.bind();
+        this.#form = this.#textarea?.form ?? this.host.closest('form');
+        this.#form?.addEventListener('submit', this.#onSubmit);
+        this.#form?.addEventListener('formdata', this.#onFormData);
+        this.#form?.addEventListener('reset', this.#onReset);
+        this.sync();
+    }
+    detach() {
+        // Flush first. A host that removes the editor and then reads the textarea
+        // -- a framework unmounting a component, a wizard swapping a step -- must
+        // not get the value as of the last debounce tick.
+        this.flush();
+        this.#form?.removeEventListener('submit', this.#onSubmit);
+        this.#form?.removeEventListener('formdata', this.#onFormData);
+        this.#form?.removeEventListener('reset', this.#onReset);
+        this.#form = null;
+    }
+    rebind() {
+        this.detach();
+        this.bind();
+        this.attach();
+    }
+    /**
+     * Write the document into the textarea.
+     *
+     * `value` is an optional already-serialized copy. The keystroke path has one
+     * in hand -- it is about to put the same string in the change event's detail
+     * -- and serializing the document twice per keystroke was measurable on a
+     * large post.
+     *
+     * An explicit sync also cancels a pending debounced one and clears the dirty
+     * flag: the write it was going to make has just happened.
+     */
+    sync(value) {
+        this.#cancel();
+        this.#dirty = false;
+        if (!this.#textarea)
+            return;
+        const html = value ?? this.readValue();
+        this.#textarea.value = html;
+        this.#written = html;
+    }
+    /**
+     * Record that the document changed, without serializing it.
+     *
+     * The serialization is what costs -- a `DOMSerializer` pass over the whole
+     * document and a ~0.33 MB string per keystroke on a 100-page document -- and
+     * nothing reads the result until one of the flush points below. So the change
+     * is only noted here, and the trailing timer exists for hosts that watch the
+     * textarea rather than the element.
+     */
+    markDirty() {
+        if (!this.#textarea)
+            return;
+        this.#dirty = true;
+        if (this.#timer !== null)
+            return;
+        this.#timer = setTimeout(() => {
+            this.#timer = null;
+            this.flush();
+        }, SYNC_DELAY_MS);
+    }
+    /**
+     * Write the document to the textarea if, and only if, it would differ.
+     *
+     * Two ways it can: the document changed since the last write, or something
+     * outside wrote to the textarea itself -- a script, a server re-render, a
+     * test. The second is why this cannot be a bare dirty check. Comparing
+     * against the string last written costs a string compare and no
+     * serialization, so the flush points stay free when nothing has moved.
+     */
+    flush() {
+        const foreign = this.#textarea !== null && this.#written !== null && this.#textarea.value !== this.#written;
+        if (this.#dirty || foreign)
+            this.sync();
+        else
+            this.#cancel();
+    }
+    #cancel() {
+        if (this.#timer === null)
+            return;
+        clearTimeout(this.#timer);
+        this.#timer = null;
+    }
+    #onSubmit = () => this.flush();
+    #onFormData = (event) => {
+        this.flush();
+        if (this.#textarea?.name)
+            event.formData.set(this.#textarea.name, this.#textarea.value);
+    };
+    #onReset = () => {
+        // Reset fires before controls restore their defaults.
+        queueMicrotask(() => {
+            if (this.#textarea)
+                this.writeValue(this.#textarea.value);
+        });
+    };
+}
+//# sourceMappingURL=form-bridge.js.map

package/dist/form-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-bridge.js","sourceRoot":"","sources":["../src/form-bridge.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -20,14 +20,31 @@
  *     reads `$_POST['body']` keeps working untouched.
  *
  * Attributes:
- *   for          id of the textarea to bind to
- *   skin         named appearance: midnight, paper, contrast, compact
- *   theme        light | dark | auto (default: follow the visitor's system)
- *   toolbar      space-separated item ids, `|` for a separator; `none` to omit
- *   readonly     render but do not allow editing
- *   aria-label   accessible name for the editable region
+ *   for              id of the textarea to bind to
+ *   skin             named appearance: midnight, paper, contrast, compact
+ *   theme            light | dark | auto (default: follow the visitor's system)
+ *   toolbar          space-separated item ids, `|` for a separator; `none` to omit
+ *   toolbar2         a second toolbar, same grammar
+ *   menubar          space-separated menu ids, or omit to hide; `none` also hides
+ *   contextmenu      `none` to disable; default is link, image and table menus
+ *   selection-toolbar floating bar for a non-empty selection; `none` disables
+ *   insert-toolbar    floating bar for an empty block; `none` disables
+ *   formats          `p.lead=Lead|h2=Section` entries for the formats dropdown
+ *   content-css      comma-separated URLs scoped onto the canvas
+ *   lang             UI locale, matched against registerTranslations()
+ *   inline           hide chrome until the editor is focused
+ *   autoresize       grow the canvas with the document
+ *   toolbar-overflow collapse overflowing groups into a More menu
+ *   readonly         render but do not allow editing
+ *   autolink         `false` to stop URLs becoming links on space or Enter.
+ *                    Trailing prose punctuation is left outside the mark.
+ *   visualaids       `false` to hide the guides for invisible structure
+ *   aria-label       accessible name for the editable region
+ *
+ * See `docs/api-reference.md` for the properties, methods and events too.
  */
-import { Toolbar } from '@openleaf-editor/ui';
+import { type ToolbarHandle, type ImageUploader } from '@openleaf-editor/ui';
+import type { Schema } from 'prosemirror-model';
 import { EditorView } from 'prosemirror-view';
 /**
  * Emitted when the HTML source view opens and closes, carrying the textarea.
@@ -36,10 +53,23 @@ import { EditorView } from 'prosemirror-view';
  * formatting, syntax highlighting -- without the element having to know anything
  * about it. Names are defined here rather than imported so the element keeps no
  * dependency on any plugin.
+ *
+ * These fire on a REAL teardown, not on a DOM move. Moving the element keeps
+ * the whole session -- including source mode and the same textarea node -- so
+ * an enhancer that attached on open stays correctly attached, and gets its
+ * close only when the element is actually removed for good.
  */
 export declare const SOURCE_OPEN_EVENT = "openleaf:source-open";
 export declare const SOURCE_CLOSE_EVENT = "openleaf:source-close";
-export declare class OpenLeafEditor extends HTMLElement {
+declare const HTMLElementBase: typeof HTMLElement;
+export interface OpenLeafChangeDetail {
+    /** The document as HTML, already serialized. */
+    value: string;
+}
+export interface OpenLeafSourceDetail {
+    textarea: HTMLTextAreaElement;
+}
+export declare class OpenLeafEditor extends HTMLElementBase {
     #private;
     static get observedAttributes(): string[];
     /**
@@ -66,17 +96,61 @@ export declare class OpenLeafEditor extends HTMLElement {
      * nothing about this is visible to an author.
      */
     connectedCallback(): void;
+    /**
+     * Tear down -- but only once the element is really gone.
+     *
+     * Moving a node fires disconnect and then connect SYNCHRONOUSLY, so a guard
+     * in `connectedCallback` can never help: by the time it runs the view has
+     * already been destroyed. Deferring the decision by one microtask makes a
+     * move a no-op, which is what keeps undo history, selection and every
+     * plugin's state alive across a keyed-list reorder, an `insertBefore`
+     * shuffle or a drag-to-reorder.
+     *
+     * The limit is worth being precise about, because it is not "unmounting is
+     * safe now": this only covers a move completed within one task. Anything that
+     * parks the element in a detached container across ticks -- Vue's
+     * `<KeepAlive>` does exactly that -- is a real removal and tears down, which
+     * is why the rebuild path has to stay correct rather than merely unreachable.
+     */
     disconnectedCallback(): void;
     /** Current document as an HTML string. */
     get value(): string;
     set value(html: string);
+    /**
+     * Uploader for this editor alone, overriding `registerImageUploader`.
+     *
+     * An accessor rather than a class field, and that is load-bearing: a field
+     * initializer runs when the element upgrades, so it would overwrite an
+     * uploader assigned before the definition loaded -- exactly the case
+     * `#upgradeProperty` exists to rescue, defeated by the declaration meant to
+     * make the property visible.
+     */
+    get imageUploader(): ImageUploader | null;
+    set imageUploader(uploader: ImageUploader | null);
     /** Escape hatch for plugins and integrations that need the real view. */
     get view(): EditorView | null;
     /** The schema this editor was built with. */
-    get schema(): import('prosemirror-model').Schema;
+    get schema(): Schema<string, string>;
     /** The toolbar, for plugins pushing external state via setItemState. */
-    get toolbar(): Toolbar | null;
+    get toolbarInstance(): ToolbarHandle | null;
+    /** The `toolbar` attribute. Assigning reflects, as HTML properties should. */
+    get toolbar(): string | null;
+    set toolbar(layout: string | null);
+    /** The `toolbar2` attribute. */
+    get toolbar2(): string | null;
+    set toolbar2(layout: string | null);
+    /** The `menubar` attribute. */
+    get menubar(): string | null;
+    set menubar(menus: string | null);
+    /** The `formats` attribute. */
+    get formats(): string | null;
+    set formats(spec: string | null);
+    /** The `readonly` attribute, as the boolean every framework binds it as. */
+    get readOnly(): boolean;
+    set readOnly(value: boolean);
+    /** Whether the HTML source view is open. Assigning toggles it. */
     get sourceMode(): boolean;
+    set sourceMode(open: boolean);
 }
 /**
  * Re-exported so the single-file bundle can offer paste normalization without a
@@ -89,7 +163,53 @@ export { normalizePastedHtml } from '@openleaf-editor/paste';
  * without a build step: `OpenLeaf.registerImageUploader(fn)`. Setting
  * `element.imageUploader` overrides it for one editor.
  */
-export { registerImageUploader, type ImageUploadResult, type ImageUploader, } from '@openleaf-editor/ui';
+export { registerFilePicker, registerImageClasses, registerImageList, registerImageUploader, registerLinkList, registerTranslations, setUiLocale, type FilePicker, type FilePickerKind, type ImageUploadResult, type ImageUploader, type ListedResource, type PickedResource, } from '@openleaf-editor/ui';
+/**
+ * Re-exported because it is the documented way to add a toolbar control and it
+ * lived in a package no install command mentions.
+ *
+ * `registerToolbarItem` is exported from `@openleaf-editor/ui`, which is a
+ * transitive dependency of this package and appears in no `npm install` line in
+ * any README. So the one extension point an integrator is most likely to reach
+ * for was reachable only by guessing at a package name. It is already in this
+ * bundle; re-exporting it costs nothing and means `registerToolbarItem` is
+ * available wherever `<openleaf-editor>` is -- including from
+ * `window.OpenLeaf` in a plain `<script>` integration, which has no other route
+ * to it at all.
+ *
+ * `t` comes with it: a custom control's label is translated by the toolbar, but
+ * anything the control builds itself has to be translated by the control.
+ */
+export { registerIcons, registerStyles, registerToolbarItem, t, type ToolbarContext, type ToolbarControl, type ToolbarItemSpec, type ToolbarSelectOption, } from '@openleaf-editor/ui';
+declare global {
+    interface HTMLElementTagNameMap {
+        'openleaf-editor': OpenLeafEditor;
+    }
+    interface HTMLElementEventMap {
+        'openleaf:change': CustomEvent<OpenLeafChangeDetail>;
+        'openleaf:source-open': CustomEvent<OpenLeafSourceDetail>;
+        'openleaf:source-close': CustomEvent<OpenLeafSourceDetail>;
+    }
+    /**
+     * The same three on `document` and `window`.
+     *
+     * `document.addEventListener` resolves against `DocumentEventMap`, not
+     * `HTMLElementEventMap`, so without these a delegated listener -- the ordinary
+     * way to watch every editor on a page, and the one `composed: true` now makes
+     * reliable from outside a shadow root -- was back to a bare `Event` and a cast
+     * to read `detail`.
+     */
+    interface DocumentEventMap {
+        'openleaf:change': CustomEvent<OpenLeafChangeDetail>;
+        'openleaf:source-open': CustomEvent<OpenLeafSourceDetail>;
+        'openleaf:source-close': CustomEvent<OpenLeafSourceDetail>;
+    }
+    interface WindowEventMap {
+        'openleaf:change': CustomEvent<OpenLeafChangeDetail>;
+        'openleaf:source-open': CustomEvent<OpenLeafSourceDetail>;
+        'openleaf:source-close': CustomEvent<OpenLeafSourceDetail>;
+    }
+}
 /** Idempotent: safe to import twice, or alongside a bundled copy. */
 export declare function defineOpenLeafEditor(tag?: string): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAcH,OAAO,EAEL,OAAO,EAYR,MAAM,qBAAqB,CAAA;AAK5B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAI7C;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AACvD,eAAO,MAAM,kBAAkB,0BAA0B,CAAA;AAEzD,qBAAa,cAAe,SAAQ,WAAW;;IAC7C,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED;;;;OAIG;IACH,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IA6C5C;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,IAAI,IAAI;IA2LzB,oBAAoB,IAAI,IAAI;IAiB5B,0CAA0C;IAC1C,IAAI,KAAK,IAAI,MAAM,CAIlB;IAED,IAAI,KAAK,CAAC,IAAI,EAAE,MAAM,EAWrB;IAED,yEAAyE;IACzE,IAAI,IAAI,IAAI,UAAU,GAAG,IAAI,CAE5B;IAED,6CAA6C;IAC7C,IAAI,MAAM,IAAI,OAAO,mBAAmB,EAAE,MAAM,CAE/C;IAED,wEAAwE;IACxE,IAAI,OAAO,IAAI,OAAO,GAAG,IAAI,CAE5B;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;CAmNF;AAED;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAE5D;;;;GAIG;AACH,OAAO,EACL,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAA;AAE5B,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,GAAG,SAAoB,GAAG,IAAI,CAIlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAqBH,OAAO,EAcL,KAAK,aAAa,EAqBlB,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAA;AAI5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAgB7C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AACvD,eAAO,MAAM,kBAAkB,0BAA0B,CAAA;AAKzD,QAAA,MAAM,eAAe,EAA2C,OAAO,WAAW,CAAA;AAElF,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AAED,qBAAa,cAAe,SAAQ,eAAe;;IACjD,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAkBxC;IAED;;;;OAIG;IACH,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAkJ5C;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,IAAI,IAAI;IA4QzB;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,IAAI,IAAI;IAyS5B,0CAA0C;IAC1C,IAAI,KAAK,IAAI,MAAM,CAoBlB;IAED,IAAI,KAAK,CAAC,IAAI,EAAE,MAAM,EAkCrB;IAUD;;;;;;;;OAQG;IACH,IAAI,aAAa,IAAI,aAAa,GAAG,IAAI,CAExC;IAED,IAAI,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,EAE/C;IAED,yEAAyE;IACzE,IAAI,IAAI,IAAI,UAAU,GAAG,IAAI,CAE5B;IAED,6CAA6C;IAC7C,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnC;IAED,wEAAwE;IACxE,IAAI,eAAe,IAAI,aAAa,GAAG,IAAI,CAE1C;IAED,8EAA8E;IAC9E,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAEhC;IAED,gCAAgC;IAChC,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,IAAI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAEjC;IAED,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAE/B;IAED,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAE9B;IAED,4EAA4E;IAC5E,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAE1B;IAOD,kEAAkE;IAClE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,EAG3B;CA6nBF;AAED;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAE5D;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,CAAC,EACD,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,cAAc,CAAA;KAClC;IACD,UAAU,mBAAmB;QAC3B,iBAAiB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;QACpD,sBAAsB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;QACzD,uBAAuB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;KAC3D;IACD;;;;;;;;OAQG;IACH,UAAU,gBAAgB;QACxB,iBAAiB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;QACpD,sBAAsB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;QACzD,uBAAuB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;KAC3D;IACD,UAAU,cAAc;QACtB,iBAAiB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;QACpD,sBAAsB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;QACzD,uBAAuB,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;KAC3D;CACF;AAED,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,GAAG,SAAoB,GAAG,IAAI,CAIlE"}