@teleporthq/teleport-shared 0.43.61 → 0.43.63

package/dist/cjs/utils/rich-text-embeds.d.ts

@@ -0,0 +1,251 @@
+/**
+ * The "code embed" contract for rich-text CONTENT — the blog post body, and any
+ * other column authored through a rich-text editor.
+ *
+ * A code embed is a block a post author drops into the body to pull in content
+ * from another site (a video, a social post, a design frame, a form, or a raw
+ * snippet they pasted). It is stored INSIDE the content HTML, so the same shape
+ * has to be produced by the studio's Quill editor, produced by the generated
+ * admin panel's Quill editor, previewed by the studio canvas and rendered by
+ * the exported Next.js app. This module is that single shape.
+ *
+ * Two rendering modes, decided by one rule (`resolveEmbedMode`):
+ *
+ *  - `inline`  — the markup is provably passive (no `<script>`, no `on*`
+ *                handler, no `javascript:` URL). It is stored as the element's
+ *                own children, so it renders server-side, needs no JavaScript
+ *                and is crawlable. Most provider embeds are a bare `<iframe>`
+ *                and land here.
+ *  - `sandbox` — anything else. The markup is base64-encoded into
+ *                `data-tq-embed-code` and the runtime materializes it inside a
+ *                sandboxed `srcdoc` iframe, so author-supplied JavaScript can
+ *                never touch the hosting page. The children hold only a
+ *                `<noscript>` link fallback.
+ *
+ * The provider registry is deliberately DECLARATIVE — patterns plus a
+ * replacement template, never functions — so `rich-text-embeds-codegen` can
+ * serialize it verbatim into the module the generated project gets, and the
+ * editor and the published site can never drift.
+ */
+export type EmbedAlign = 'center' | 'float-left' | 'float-right';
+export type EmbedMode = 'inline' | 'sandbox';
+/**
+ * `strict` (the default) omits `allow-same-origin`, so the embed runs in an
+ * opaque origin and cannot reach the host page's storage or DOM. `trusted` adds
+ * it back for the widgets that refuse to render without storage access — an
+ * explicit, per-embed opt-in the author has to make.
+ */
+export type EmbedSandboxLevel = 'strict' | 'trusted';
+export interface EmbedValue {
+    /** Registry id, or `custom` when the author pasted the markup themselves. */
+    provider: string;
+    /** The source URL, when there was one. Lets the editor re-open the Link tab. */
+    url: string;
+    /** The embed markup itself. */
+    code: string;
+    mode: EmbedMode;
+    /** Responsive box height as a padding-top percentage; `null` = intrinsic. */
+    ratio: number | null;
+    /** Block width as a percentage of the content column, 10-100. */
+    width: number;
+    align: EmbedAlign;
+    caption: string;
+    sandboxLevel: EmbedSandboxLevel;
+}
+export declare const EMBED_CLASS_NAME = "tq-embed";
+export declare const EMBED_FRAME_CLASS_NAME = "tq-embed-frame";
+export declare const EMBED_CAPTION_CLASS_NAME = "tq-embed-caption";
+/** The Quill blot name, shared by the studio editor and the generated one. */
+export declare const EMBED_BLOT_NAME = "tq-embed";
+export declare const EMBED_ATTR: {
+    readonly MARKER: "data-tq-embed";
+    readonly PROVIDER: "data-tq-embed-provider";
+    readonly URL: "data-tq-embed-url";
+    readonly MODE: "data-tq-embed-mode";
+    readonly CODE: "data-tq-embed-code";
+    readonly RATIO: "data-tq-embed-ratio";
+    readonly WIDTH: "data-tq-embed-width";
+    readonly ALIGN: "data-tq-embed-align";
+    readonly CAPTION: "data-tq-embed-caption";
+    readonly SANDBOX: "data-tq-embed-sandbox";
+    /** Written by a runtime once a sandbox embed has been mounted. */
+    readonly ACTIVATED: "data-tq-embed-activated";
+    /**
+     * Marks an element an EDITOR added purely to preview the embed. Editors read
+     * their value back out of the live DOM, so a preview must be recognizable in
+     * order to be stripped again — see `normalizeEmbedsForStorage`.
+     */
+    readonly PREVIEW: "data-tq-embed-preview";
+};
+export declare const EMBED_ALIGNMENTS: EmbedAlign[];
+export declare const CUSTOM_EMBED_PROVIDER_ID = "custom";
+export declare const GENERIC_EMBED_PROVIDER_ID = "iframe-url";
+export declare const DEFAULT_EMBED_WIDTH = 100;
+export declare const DEFAULT_EMBED_ALIGN: EmbedAlign;
+export declare const DEFAULT_EMBED_SANDBOX_LEVEL: EmbedSandboxLevel;
+/** 16:9, as a padding-top percentage. */
+export declare const WIDESCREEN_EMBED_RATIO = 56.25;
+export interface EmbedProviderDefinition {
+    id: string;
+    label: string;
+    /**
+     * Alternative spellings of the same URL. Every pattern of one provider must
+     * expose the same capture groups, because `template` indexes them by number.
+     */
+    patterns: RegExp[];
+    /**
+     * The markup, with `$1`-`$9` replaced by the capture groups and `$&` by the
+     * whole URL. Prefix the token with `E` (`$E1`, `$E&`) to URL-encode it.
+     * A literal dollar is written `$$`.
+     */
+    template: string;
+    /**
+     * When set, the frame becomes a responsive padding-top box of this
+     * percentage and the template's iframe is expected to fill it absolutely.
+     * `null` means the template carries its own height.
+     */
+    ratio: number | null;
+}
+/**
+ * Ordered most-specific first: `resolveEmbedProvider` returns the first match,
+ * and the generic `iframe-url` fallback is deliberately last.
+ */
+export declare const EMBED_PROVIDERS: EmbedProviderDefinition[];
+export interface EmbedProviderMatch {
+    provider: EmbedProviderDefinition;
+    match: RegExpMatchArray;
+}
+/** `javascript:`, `data:` and protocol-relative URLs never become an embed. */
+export declare function isSafeEmbedUrl(url: string): boolean;
+/** How an embed names itself in the editor: the provider, or "Custom code". */
+export declare function embedProviderLabel(providerId: string): string;
+export declare function resolveEmbedProvider(url: string): EmbedProviderMatch | null;
+/**
+ * Substitutes `$1`-`$9` / `$E1`-`$E9` / `$&` / `$E&` in a provider template.
+ * Written by hand rather than through `String.replace` so the replacement
+ * patterns `String.replace` reserves (`$'`, "$`", `$<name>`) stay literal.
+ */
+export declare function applyEmbedTemplate(template: string, match: RegExpMatchArray, url: string): string;
+/** The embed markup for a pasted URL, or `null` when nothing recognizes it. */
+export declare function buildEmbedHtmlFromUrl(url: string): {
+    provider: EmbedProviderDefinition;
+    html: string;
+} | null;
+/**
+ * Markup that can execute anything — a `<script>`, an inline `on*` handler or a
+ * `javascript:` URL — is quarantined in a sandboxed iframe. Everything else is
+ * passive and can be rendered straight into the page.
+ */
+export declare function resolveEmbedMode(html: string): EmbedMode;
+export declare function clampEmbedWidth(width: number): number;
+export declare function normalizeEmbedAlign(align: string): EmbedAlign;
+export declare function escapeEmbedAttribute(value: string): string;
+export declare function escapeEmbedText(value: string): string;
+/**
+ * UTF-8 safe base64, working in both the browser (`btoa`) and Node (`Buffer`).
+ * The intermediate `%xx` round-trip is what makes non-ASCII captions and
+ * markup survive — `btoa` alone throws on anything above U+00FF.
+ */
+export declare function encodeEmbedCode(code: string): string;
+export declare function decodeEmbedCode(encoded: string): string;
+export declare function createEmbedValue(params: {
+    code: string;
+    provider?: string;
+    url?: string;
+    ratio?: number | null;
+    width?: number;
+    align?: string;
+    caption?: string;
+    sandboxLevel?: EmbedSandboxLevel;
+}): EmbedValue;
+/**
+ * The outer block's own layout — width, float and the margins each align needs.
+ *
+ * `position:relative` is deliberate: an editor overlays a click catcher on the
+ * block (an embed's own iframe swallows the click that should select it), and
+ * that overlay needs the block as its positioning context.
+ */
+export declare function embedBlockStyle(value: Pick<EmbedValue, 'width' | 'align'>): string;
+/**
+ * The frame is what holds the embed itself. With a `ratio` it becomes the
+ * responsive padding-top box the provider templates fill absolutely; without
+ * one the template carries its own height.
+ */
+export declare function embedFrameStyle(ratio: number | null): string;
+export declare const EMBED_CAPTION_STYLE = "margin-top:8px;font-size:0.875em;line-height:1.5;opacity:0.75;text-align:center";
+/**
+ * The stored markup for one embed. This is the exact string both editors write
+ * into the content column and both runtimes read back.
+ */
+export declare function buildEmbedElementHtml(value: EmbedValue): string;
+/**
+ * `inline` keeps the markup as real children so it renders with no JavaScript.
+ * `sandbox` keeps only a `<noscript>` link — the markup itself lives, encoded,
+ * on `data-tq-embed-code` and the runtime mounts it in a sandboxed iframe.
+ */
+export declare function buildEmbedFrameChildren(value: EmbedValue): string;
+export declare function findEmbedFrame(element: Element): Element | null;
+export declare function readEmbedValueFromElement(element: Element): EmbedValue;
+/**
+ * A corrupted `data-tq-embed-code` (truncated by an export round-trip, mangled
+ * by a content rewrite) must degrade to "render nothing", never to a thrown
+ * exception inside a render pass.
+ */
+export declare function readEncodedEmbedCode(element: Element): string;
+export declare function applyEmbedElementLayout(element: Element, updates: {
+    width?: number;
+    align?: string;
+}): void;
+/**
+ * Adds, updates or removes the caption element in place. The caption lives both
+ * as an attribute (so it survives a sandbox re-render) and as visible text.
+ */
+export declare function applyEmbedElementCaption(element: Element, caption: string): void;
+/**
+ * `allow-same-origin` is deliberately absent: combined with `allow-scripts` it
+ * lets a frame reach into the host page and even remove its own sandbox, which
+ * is the whole thing this mode exists to prevent.
+ */
+export declare const EMBED_SANDBOX_FLAGS_STRICT = "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms allow-presentation";
+/** The opt-in for widgets that refuse to render without storage access. */
+export declare const EMBED_SANDBOX_FLAGS_TRUSTED: string;
+export declare function resolveEmbedSandboxFlags(level: EmbedSandboxLevel): string;
+export declare const EMBED_HEIGHT_MESSAGE_TYPE = "tq-embed-height";
+export declare const EMBED_TOKEN_PLACEHOLDER = "__TQ_EMBED_TOKEN__";
+export declare const EMBED_MIN_HEIGHT = 80;
+export declare const EMBED_MAX_HEIGHT = 6000;
+/** Until the frame reports back, this is what it occupies. */
+export declare const EMBED_INITIAL_HEIGHT = 320;
+export declare const EMBED_SANDBOX_DOC_HEAD: string;
+export declare const EMBED_SANDBOX_DOC_TAIL = "</body></html>";
+/**
+ * The document a sandboxed embed is given. Assign it to `iframe.srcdoc` as a
+ * property — writing it into the attribute would need HTML escaping.
+ */
+export declare function buildEmbedSandboxDocument(code: string, token: string): string;
+/**
+ * A sandboxed frame has an opaque origin, so `event.origin` is `"null"` and
+ * cannot identify it. The per-frame token baked into its document is the guard
+ * instead: a message is only ever matched against tokens this page minted.
+ */
+export declare function parseEmbedHeightMessage(data: unknown): {
+    token: string;
+    height: number;
+} | null;
+export declare function createEmbedToken(): string;
+/**
+ * Restores every embed inside `root` to its canonical STORED form, in place.
+ *
+ * An editor reads its value back out of the live DOM (Quill hands back
+ * `root.innerHTML`), and by then the DOM carries things the content column must
+ * never keep: the preview an editor mounted next to a sandboxed embed, and the
+ * marker a runtime writes once it has handled a block. The editor normalizes a
+ * detached CLONE of its root through this before emitting a value, so what is
+ * stored is exactly what `buildEmbedElementHtml` would have produced — whatever
+ * the preview did to the live DOM.
+ *
+ * The frame restore is a self-heal for the other mounting strategy: the canvas
+ * and the published page mount INTO the frame, because they never read back.
+ */
+export declare function normalizeEmbedsForStorage(root: Element): void;
+//# sourceMappingURL=rich-text-embeds.d.ts.map

package/dist/cjs/utils/rich-text-embeds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-text-embeds.d.ts","sourceRoot":"","sources":["../../../src/utils/rich-text-embeds.ts"],"names":[],"mappings":"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"}