@hyper-elements/react 0.0.0-stage → 0.3.0

package/dist/builder.d.cts

@@ -0,0 +1,89 @@
+import React from 'react';
+
+/**
+ * The builder's design JSON as a template in the new components, from its values alone: the body is the root (the
+ * builder's display mode), with its rows (rows.ts) in it, a Document's header and footer around them. Malformed JSON
+ * never throws: what can't be read is left out and said.
+ */
+
+type DisplayMode = "email" | "web" | "document";
+
+/**
+ * A design's values as Elements 0.2's components read them, which is how the builder draws them: lengths, sides, colors,
+ * borders, line heights, weights, fonts, alignments and links (as the new engine's), email services' tags, the id an
+ * author gave a part, where it's hidden, and a text tool's link style. fromDesign() reads designs with these; today's
+ * components' lowering (src/compat) reads them with the same.
+ */
+
+type Values = Record<string, any>;
+
+type DesignRow = {
+    cells: number[];
+    columns: Array<{
+        contents: Array<{
+            type: string;
+            values: Values;
+        }>;
+        values: Values;
+    }>;
+    values: Values;
+};
+type Design = {
+    counters?: Record<string, number>;
+    schemaVersion?: number;
+    body: {
+        rows: DesignRow[];
+        values: Values;
+        headers?: DesignRow[];
+        footers?: DesignRow[];
+    };
+};
+
+/**
+ * The writing half of toDesign(): a template as the builder's rows, columns and blocks (raise.ts), each with its exact
+ * values and hidden properties, written as the builder's design JSON (design.ts).
+ */
+
+interface DesignResult {
+    /** The builder's design JSON, for loadDesign(). */
+    design: Design;
+    /** What the builder can't hold as it is (a block of HTML, a style left out): one line each. */
+    report: string[];
+}
+
+/**
+ * The builder adapter: a template in the new components as the Unlayer builder's design JSON, and
+ * a design (edited in the builder or not) back as a template. The design holds no Elements data: a style or prop a
+ * tool has no field for is a hidden property of that tool (manifest.ts), kept in the design with no editor yet. What
+ * the builder can't arrange comes back as the builder holds it: the same look, flatter.
+ */
+
+/** A template in the new components (an `<Email>`, a `<Page>` or a `<Document>`) as the builder's design JSON. */
+declare function toDesign(element: React.ReactElement): DesignResult;
+interface TemplateResult {
+    /** The template, to render. */
+    element: React.ReactElement;
+    /** The template as JSX source in the new components. */
+    code: string;
+    /** What of the design the template can't hold, and what was left out: one line each. */
+    report: string[];
+}
+interface FromDesignOptions {
+    /**
+     * The builder's display mode the design was made in: its root. "email" is an Email, "web" a Page, "document" a
+     * Document. Without one, a design with a header, a footer or a page break is a Document, any other an Email.
+     */
+    displayMode?: DisplayMode;
+    /** The name of the component in `code`. */
+    name?: string;
+    /**
+     * Your sanitizer for a design's markup, as today's exporters take it in their config: every builder `html` block's
+     * markup, and every text's (before it's read, as theirs is), goes through it. Without one, a design's markup is
+     * kept as it is: give one where a design can hold untrusted content.
+     */
+    toSafeHtml?: (html: string) => string;
+}
+/** The builder's design JSON (made by toDesign() or in the builder) as a template in the new components. */
+declare function fromDesign(design: unknown, options?: FromDesignOptions): TemplateResult;
+
+export { type Design, type DesignResult, type DisplayMode, type FromDesignOptions, type TemplateResult, fromDesign, toDesign };

package/dist/builder.d.ts

@@ -0,0 +1,89 @@
+import React from 'react';
+
+/**
+ * The builder's design JSON as a template in the new components, from its values alone: the body is the root (the
+ * builder's display mode), with its rows (rows.ts) in it, a Document's header and footer around them. Malformed JSON
+ * never throws: what can't be read is left out and said.
+ */
+
+type DisplayMode = "email" | "web" | "document";
+
+/**
+ * A design's values as Elements 0.2's components read them, which is how the builder draws them: lengths, sides, colors,
+ * borders, line heights, weights, fonts, alignments and links (as the new engine's), email services' tags, the id an
+ * author gave a part, where it's hidden, and a text tool's link style. fromDesign() reads designs with these; today's
+ * components' lowering (src/compat) reads them with the same.
+ */
+
+type Values = Record<string, any>;
+
+type DesignRow = {
+    cells: number[];
+    columns: Array<{
+        contents: Array<{
+            type: string;
+            values: Values;
+        }>;
+        values: Values;
+    }>;
+    values: Values;
+};
+type Design = {
+    counters?: Record<string, number>;
+    schemaVersion?: number;
+    body: {
+        rows: DesignRow[];
+        values: Values;
+        headers?: DesignRow[];
+        footers?: DesignRow[];
+    };
+};
+
+/**
+ * The writing half of toDesign(): a template as the builder's rows, columns and blocks (raise.ts), each with its exact
+ * values and hidden properties, written as the builder's design JSON (design.ts).
+ */
+
+interface DesignResult {
+    /** The builder's design JSON, for loadDesign(). */
+    design: Design;
+    /** What the builder can't hold as it is (a block of HTML, a style left out): one line each. */
+    report: string[];
+}
+
+/**
+ * The builder adapter: a template in the new components as the Unlayer builder's design JSON, and
+ * a design (edited in the builder or not) back as a template. The design holds no Elements data: a style or prop a
+ * tool has no field for is a hidden property of that tool (manifest.ts), kept in the design with no editor yet. What
+ * the builder can't arrange comes back as the builder holds it: the same look, flatter.
+ */
+
+/** A template in the new components (an `<Email>`, a `<Page>` or a `<Document>`) as the builder's design JSON. */
+declare function toDesign(element: React.ReactElement): DesignResult;
+interface TemplateResult {
+    /** The template, to render. */
+    element: React.ReactElement;
+    /** The template as JSX source in the new components. */
+    code: string;
+    /** What of the design the template can't hold, and what was left out: one line each. */
+    report: string[];
+}
+interface FromDesignOptions {
+    /**
+     * The builder's display mode the design was made in: its root. "email" is an Email, "web" a Page, "document" a
+     * Document. Without one, a design with a header, a footer or a page break is a Document, any other an Email.
+     */
+    displayMode?: DisplayMode;
+    /** The name of the component in `code`. */
+    name?: string;
+    /**
+     * Your sanitizer for a design's markup, as today's exporters take it in their config: every builder `html` block's
+     * markup, and every text's (before it's read, as theirs is), goes through it. Without one, a design's markup is
+     * kept as it is: give one where a design can hold untrusted content.
+     */
+    toSafeHtml?: (html: string) => string;
+}
+/** The builder's design JSON (made by toDesign() or in the builder) as a template in the new components. */
+declare function fromDesign(design: unknown, options?: FromDesignOptions): TemplateResult;
+
+export { type Design, type DesignResult, type DisplayMode, type FromDesignOptions, type TemplateResult, fromDesign, toDesign };