@hyper-elements/react 0.3.0 → 0.3.1

package/dist/inspect.d.cts

@@ -0,0 +1,472 @@
+import React from 'react';
+
+/**
+ * The template tree: what a template's JSX is collected into inside one
+ * render, and what layout and every writer read. Internal, never public; plain
+ * data (no functions, no React elements).
+ */
+type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+interface Node {
+    /** Only when the author gives one; unique in the template, and written to the HTML as is. */
+    id?: string;
+    /** A defined component: "Email", "Row", "Heading", … */
+    type: string;
+    /** Meaning: href, src, alt, level. */
+    props?: Record<string, Json>;
+    /** Appearance, in the value kinds the component's definition gives. */
+    style?: Record<string, Json>;
+    /** Style overrides on phones (Email and Page). */
+    mobile?: Record<string, Json>;
+    /** Style while the pointer is over it, where the definition allows. */
+    hover?: Record<string, Json>;
+    hidden?: {
+        mobile?: boolean;
+        desktop?: boolean;
+    };
+    children?: Child[];
+}
+/** A string is text, where the parent takes text. */
+type Child = Node | string;
+
+/**
+ * The email clients Elements checks an Email for. Four were captured showing Elements 0.3.0 emails they weren't tuned
+ * on (unlayer/email-renderer), which says how closely each is measured; what's known of the rest is from caniemail's
+ * tables (caniemail.com, MIT), which test the CSS and HTML each client keeps. Either way a problem is said at its own
+ * severity; only one Elements assumes, unchecked, is a note.
+ */
+
+type EmailClient = "outlook" | "outlook-com" | "outlook-mac" | "outlook-app" | "gmail" | "gmail-app" | "gmail-app-other" | "apple-mail" | "yahoo" | "aol" | "samsung-email" | "thunderbird" | "protonmail" | "fastmail" | "hey" | "gmx" | "web-de" | "orange" | "sfr" | "laposte" | "free-fr" | "t-online-de" | "mail-ru" | "ionos" | "wp-pl" | "rainloop";
+
+/**
+ * What validation, resolution and conversion found: one list, each entry
+ * naming the node (by id where it has one) and the path to the value.
+ */
+
+type Severity = "error" | "warning" | "info";
+interface Diagnostic {
+    /** Stable, for tools to match on: "prop/unknown", "layout/overflow", … */
+    code: string;
+    severity: Severity;
+    message: string;
+    /** Where in the input: `root.children[1].style.padding`. */
+    path: string;
+    /** The node's id, once it has one. */
+    nodeId?: string;
+    /** The email clients it's about; absent: every email, never left out by `emailClients`. */
+    clients?: EmailClient[];
+    /** What to change. */
+    fix?: string;
+    /** Where to see it: for a problem known from caniemail's tables, its page there. */
+    see?: string;
+}
+
+/**
+ * Value kinds: what a prop or style property accepts, what it's normalized to,
+ * the editor that edits it, and a JSON Schema of its values (for property
+ * discovery). Component definitions are made of these, so types, validation
+ * and editors come from one place.
+ */
+
+type JsonSchema = {
+    [key: string]: unknown;
+};
+/** Conceptual editors, mapped by each editor (the builder, others) to its own widgets. */
+type EditorKind = "color" | "length" | "insets" | "border" | "radius" | "choice" | "fontFamily" | "fontFaces" | "items" | "fontWeight" | "lineHeight" | "image" | "link" | "text" | "number" | "toggle";
+type Parsed<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+};
+interface Kind<In = unknown, Out extends Json = Json> {
+    readonly name: string;
+    readonly editor: EditorKind;
+    /** What it accepts, in words (for messages and descriptions). */
+    readonly accepts: string;
+    parse(input: unknown): Parsed<Out>;
+    /** Whether a value it parsed sets nothing (`breakpoints={{}}`): the prop is then left out, as if not given. */
+    empty?(value: Out): boolean;
+    jsonSchema(): JsonSchema;
+    /** Type only: what it accepts as input. */
+    readonly __in?: In;
+}
+type OutputOf<K> = K extends Kind<unknown, infer O> ? O : never;
+
+/**
+ * Component definitions: one per component, the source of its props, styles,
+ * children, targets, support in each output and editors. Types, validation,
+ * the support pass and property discovery are all read from these.
+ */
+
+/** What a component is, for the nesting rules: a component belongs to one or more. */
+type Category = "root" | "section" | "layout" | "block" | "inline" | "shape";
+/** The outputs Elements renders. */
+type Target = "email" | "web" | "print" | "pdf" | "image";
+/** The roots a template can have: each decides the output (`render()` writes an Email's HTML, a Page's, …). */
+type RootName = "Email" | "Page" | "Document" | "Canvas";
+/** What a style is about, for the guide and `describeComponents()`: the group it's listed in. */
+type StyleGroup = "Layout" | "Size" | "Position" | "Spacing" | "Typography" | "Background" | "Border" | "Effects";
+interface PropSpec<K extends Kind<any, any> = Kind<any, any>, R extends boolean = boolean> {
+    kind: K;
+    required?: R;
+    label: string;
+    description?: string;
+    /**
+     * The roots it may be given under (default: every root its component goes in). Under another root it's a
+     * `prop/not-supported` error naming these.
+     */
+    roots?: readonly RootName[];
+    /** Used where the prop isn't given (not written into the document). */
+    default?: OutputOf<K>;
+    /** Editors may change it (default true). */
+    editable?: boolean;
+    /** How each output shows it: required for every output its component renders to (a test checks). */
+    support?: SupportByTarget;
+}
+/** A style's or prop's support, by output. */
+type SupportByTarget = Partial<Record<Target, Support | readonly Support[]>>;
+/**
+ * Where what an output shows of a style or prop is known from: captures of
+ * real classic Outlook for Windows; caniemail's client tables
+ * (caniemail.com); the output's writer itself, which turns it into markup the
+ * output shows (checked in Chromium, for email with and without <style>, and
+ * against a model of Outlook's layout built from those captures); captures of
+ * Gmail, Outlook.com or Apple Mail; CSS written as is, which browsers show as
+ * asked; or assumed, not yet checked.
+ */
+type SupportSource = "outlook-captures" | "gmail-captures" | "outlook-com-captures" | "apple-mail-captures" | "caniemail" | "writer" | "css" | "assumed";
+/**
+ * How an output shows a style or prop, or some of its values (`values`, or
+ * `when` the value, on a node with such props, is such): as asked (`full`); as asked but in classic
+ * Outlook, which shows something else (`outlook`, email only: what it shows);
+ * not quite as asked anywhere it's shown (`partial`: what it shows); or not at
+ * all (`none`: what it does instead). Read by the support pass every output
+ * runs: `outlook` and `partial` are notes, `none` a warning, whether the email
+ * clients it names were captured or are from caniemail's tables; one `assumed`
+ * is only ever a note.
+ */
+type Support = {
+    level: "full";
+    source: SupportSource;
+} | {
+    level: "outlook" | "partial" | "none";
+    shows: string;
+    values?: readonly Json[];
+    when?: (value: Json, node: {
+        props: Record<string, Json>;
+    }) => boolean;
+    source: SupportSource;
+    /** For email, the clients it's about (`outlook`: classic Outlook); absent, every email client. */
+    clients?: readonly EmailClient[];
+    /** caniemail's feature the clients are from (its slug), checked against its tables (test/caniemail.test.ts). */
+    feature?: string;
+    /** What to change. */
+    fix?: string;
+};
+interface StyleSpec<K extends Kind<any, any> = Kind<any, any>> {
+    kind: K;
+    label: string;
+    description?: string;
+    /** Passed down to children that don't set it (text styles). */
+    inherited?: boolean;
+    /** May be overridden on phones (`mobile`). */
+    mobile?: boolean;
+    /**
+     * The roots it may be set under (default: every root its component goes in). Under another root it's a
+     * `style/not-supported` error naming these, in `style` and in its condition blocks alike.
+     */
+    roots?: readonly RootName[];
+    /** The group it's listed in; default: the group of its name (`STYLE_GROUP_OF`), as a style's name is CSS's. */
+    group?: StyleGroup;
+    editable?: boolean;
+    /** How each output shows it: required for every output its component renders to (a test checks). */
+    support?: SupportByTarget;
+}
+type PropSpecs = Record<string, PropSpec>;
+type StyleSpecs = Record<string, StyleSpec>;
+interface ChildrenRule {
+    /** Text (strings) may be children. */
+    text?: boolean;
+    /** Components of these categories may be children. */
+    categories?: readonly Category[];
+    /** These types may be children, whatever their category. */
+    types?: readonly string[];
+}
+interface TargetSupport {
+    /** What's different in this target, for docs and diagnostics. */
+    note?: string;
+}
+/** A change to a node: what a composite editor writes. */
+interface NodePatch {
+    props?: Record<string, Json | undefined>;
+    style?: Record<string, Json | undefined>;
+    hover?: Record<string, Json | undefined>;
+}
+/** An editor that reads and writes several props at once (a button's colors). */
+interface CompositeEditor<V = any> {
+    /** The conceptual editor ("buttonColors"); editors map it to a widget. */
+    editor: string;
+    /** The paths it reads and writes ("style.color", "hover.backgroundColor"). */
+    covers: readonly string[];
+    read(node: Pick<Node, "props" | "style" | "hover">): V;
+    write(value: V): NodePatch;
+}
+type EditorGroup = {
+    title: string;
+    paths: readonly string[];
+} | {
+    title: string;
+    composite: CompositeEditor;
+};
+/**
+ * A component's definition. `H` is its hover styles' keys: a definition made with `defineComponent()` keeps the list it
+ * gives (none: `readonly []`), so the types of its `style.hover` can be exactly those; the default is any of its styles.
+ */
+interface ComponentDefinition<P extends PropSpecs = PropSpecs, S extends StyleSpecs = StyleSpecs, H extends readonly (keyof S & string)[] = readonly (keyof S & string)[]> {
+    type: string;
+    label: string;
+    description: string;
+    categories: readonly Category[];
+    props: P;
+    style: S;
+    /** The component's own style, under what the author sets and over what's inherited (as a browser's defaults are). */
+    defaultStyle?: {
+        [K in keyof S]?: OutputOf<S[K]["kind"]>;
+    };
+    /** Default style that depends on a prop's value (a Heading's size on its level), over `defaultStyle`. */
+    defaultStyleBy?: {
+        prop: keyof P & string;
+        values: Record<string, {
+            [K in keyof S]?: OutputOf<S[K]["kind"]>;
+        }>;
+    };
+    /** Style keys that may be set for `hover`. */
+    hover?: H;
+    /**
+     * Styles a condition takes on this component that an output doesn't show under it, by condition, style and
+     * output (a Page root's phone font size): reported when the template is expanded, before a Grid is arranged.
+     */
+    conditionSupport?: Partial<Record<"mobile" | "hover", Partial<Record<keyof S & string, SupportByTarget>>>>;
+    children: ChildrenRule;
+    /**
+     * How wide it is where nothing sets its width: `stretch` fills its parent's
+     * content width; `shrink` takes its own size (an image's, a button's
+     * content).
+     */
+    sizing: "stretch" | "shrink" | "none";
+    /** A root that has a phone width (Email, Page): `mobile` and `hidden` apply under it. */
+    responsive?: boolean;
+    /**
+     * A built-in that lays its children out with other components (a Grid's Rows of Columns): its node as those,
+     * before layout. Its children (and their ids) are kept as they are.
+     */
+    arrange?: (node: Node) => Node;
+    /** Where it renders; a target left out is a diagnostic. */
+    targets: Partial<Record<Target, TargetSupport>>;
+    /**
+     * The roots it may go in, of those whose output it renders to (default: every one whose children reach it). Under
+     * another such root it's the `notAllowed` error, by default `component/not-supported` naming these; under a root
+     * whose output it doesn't render to, it's `target/unsupported`, as for any component.
+     */
+    roots?: readonly RootName[];
+    notAllowed?: {
+        code: string;
+        message: (root: string) => string;
+    };
+    /** Why a target it doesn't render can't, and what to do instead (in the diagnostic). */
+    unsupported?: Partial<Record<Target, string>>;
+    editor?: {
+        groups: readonly EditorGroup[];
+    };
+}
+
+/**
+ * The conditions a component's styles can be set for besides its own: on phones (`mobile`) and while the pointer is
+ * over it (`hover`). Each says where it's allowed, which styles it takes, where its rules go in the stylesheet, and
+ * how each output shows it, so reading a template, expanding composites, the support diagnostics and the writers all
+ * go through this one list. A condition joins it with its support for every output (test/writers/support.test.ts).
+ */
+
+type ConditionName = "mobile" | "hover";
+/** On any child, read by the Row it's in. */
+declare const placementStyle: {
+    flex: {
+        kind: Kind<number | "none", number | "none">;
+        label: string;
+        description: string;
+        support: {
+            email: {
+                level: "full";
+                source: SupportSource;
+            };
+            web: {
+                level: "full";
+                source: SupportSource;
+            };
+        };
+    };
+};
+/** Props that always have a value: required ones, and ones with a default (see `prop`). */
+type RequiredOrDefaulted<P extends PropSpecs> = {
+    [K in keyof P]: Exclude<P[K]["required"], undefined> extends true ? K : [P[K]["default"]] extends [undefined] ? never : K;
+}[keyof P];
+/** The props `expand` (or a `render`) gets: normalized, with defaults applied. */
+type ExpandProps<P extends PropSpecs> = {
+    [K in RequiredOrDefaulted<P>]: OutputOf<P[K]["kind"]>;
+} & {
+    [K in Exclude<keyof P, RequiredOrDefaulted<P>>]?: OutputOf<P[K]["kind"]>;
+};
+/** What `expand` may do besides returning its node, and what it may read besides its props. */
+interface ExpandContext {
+    /** Makes custom components the expansion uses known (ones not passed in the components option). */
+    register(definition: CustomDefinition<any>): void;
+    /** The node's style, with its definition's defaults: a built-in made of primitives (Social, Menu) styles them by it. */
+    style: Record<string, Json>;
+    /** Whether the template has phones (an Email or a Page): what's hidden on phones is only hidden there. */
+    responsive: boolean;
+    /** A problem found while expanding that doesn't stop it (a warning or a note), said once at the expansion's place. */
+    report(diagnostic: Diagnostic): void;
+}
+interface CustomDefinition<P extends PropSpecs = PropSpecs> extends ComponentDefinition<P, typeof placementStyle> {
+    custom: true;
+    /**
+     * The component as primitives: one node of the template tree
+     * (`{ type, props, style, children }`). Pure: the same props give the same node.
+     */
+    expand(props: ExpandProps<P>, context: ExpandContext): unknown;
+}
+
+/**
+ * Property discovery: what a component takes and how each thing is edited, as
+ * plain data for editors, docs and agents. Each component, prop and style says
+ * which roots take it, read from the definitions (the same ones validation reads).
+ */
+
+interface PropertyDescription {
+    /** "props.href", "style.padding", "hover.color". */
+    path: string;
+    label: string;
+    description?: string;
+    kind: string;
+    accepts: string;
+    editor: EditorKind;
+    editable: boolean;
+    required: boolean;
+    default?: Json;
+    inherited: boolean;
+    mobile: boolean;
+    /** The roots it may be given under: those of its component's that it's declared for. */
+    roots: RootName[];
+    /** A style's group ("Typography", "Spacing", …); props have none. */
+    group?: StyleGroup;
+    schema: JsonSchema;
+}
+interface ComponentDescription {
+    type: string;
+    label: string;
+    description: string;
+    categories: readonly Category[];
+    properties: PropertyDescription[];
+    children: {
+        text: boolean;
+        categories: readonly Category[];
+        types: readonly string[];
+    };
+    targets: Target[];
+    /** The roots it may go in: those whose output it renders to, whose children reach it, and that it's declared for. */
+    roots: RootName[];
+    /** Editor groups: the paths each shows, or the composite editor and the paths it covers. */
+    groups: Array<{
+        title: string;
+        paths: readonly string[];
+        composite?: string;
+    }>;
+}
+
+/**
+ * `@hyper-elements/react/inspect`: what each root takes, and what a template holds, as data, without rendering
+ * anything. For an agent's tool call or an editor: "can I use this here?" before writing, and "is each part of this
+ * template allowed in its root?" after. Read from the components' definitions, the same ones validation and the
+ * generated guide read, so the three agree. Synchronous; it loads no engine, browser or network.
+ *
+ * Every result carries `version`: its shape changes only with a new version.
+ */
+
+/** The shape of what this entry returns: a new version is a new shape. */
+declare const INSPECT_VERSION = 1;
+/** A template's own component (made with `component()`), described alongside the built-in ones. */
+interface WithDefinition {
+    definition: CustomDefinition<any>;
+}
+interface DescribeOptions {
+    /** Only what this root takes, with phone styles only under a root that has phones. */
+    root?: RootName;
+    /** A template's own components (made with `component()`), described with the built-in ones. */
+    components?: readonly WithDefinition[];
+}
+interface ConditionDescription {
+    /** "mobile", "hover": the block of `style` it's written in. */
+    name: ConditionName;
+    /** "on phones", "on hover". */
+    on: string;
+    /** The roots it may be set under. */
+    roots: RootName[];
+}
+interface ComponentsDescription {
+    version: typeof INSPECT_VERSION;
+    /** The root it's narrowed to, if one was given. */
+    root?: RootName;
+    /** The roots a template can have. */
+    roots: RootName[];
+    /** Each component, with its props and styles: their kinds, groups, defaults and the roots that take them. */
+    components: ComponentDescription[];
+    /** The style blocks a component may have besides its own style, and the roots that take each. */
+    conditions: ConditionDescription[];
+}
+/**
+ * Every component a template can use (the built-in ones and those given), each with its props and styles: what
+ * each takes, its group, its default, and the roots that take it. With `root`, only what that root takes.
+ */
+declare function describeComponents(options?: DescribeOptions): ComponentsDescription;
+/** One component, as `describeComponents()` describes it; undefined where there's no such component, or `root` doesn't take it. */
+declare function describeComponent(type: string, options?: DescribeOptions): (ComponentDescription & {
+    version: typeof INSPECT_VERSION;
+}) | undefined;
+interface InspectedNode {
+    /** Where it is, as diagnostics say it: "root", "root.children[2]". */
+    path: string;
+    type: string;
+    id?: string;
+    /** The roots its component may go in. */
+    roots: RootName[];
+    /** Whether the template's root takes it. */
+    allowed: boolean;
+    /** What it's given, as written: "props.href", "style.padding", "mobile.fontSize", "hover.color", "hidden.mobile". */
+    given: string[];
+    /** The problems found on it (its props, styles and blocks, and what it renders), not on its children. */
+    problems: Diagnostic[];
+}
+interface Inspection {
+    version: typeof INSPECT_VERSION;
+    /** The template's root, or null where it has none Elements knows. */
+    root: RootName | null;
+    /** No errors (there may be warnings and notes), as `validate()` says. */
+    valid: boolean;
+    /**
+     * Each component in the template, in document order, as written: one its root doesn't take is here too, with
+     * `allowed: false` and its error in `problems`. Each `path` is the one diagnostics give.
+     */
+    nodes: InspectedNode[];
+    /** Everything found, as `validate()` finds it. */
+    diagnostics: Diagnostic[];
+}
+/**
+ * What a template holds, as data: each component, what it's given, whether its root takes it, and the problems
+ * found on it. It checks what `validate()` checks, without rendering.
+ */
+declare function inspect(element: React.ReactElement): Inspection;
+
+export { type ComponentDescription, type ComponentsDescription, type ConditionDescription, type ConditionName, type DescribeOptions, type Diagnostic, INSPECT_VERSION, type InspectedNode, type Inspection, type PropertyDescription, type RootName, type StyleGroup, describeComponent, describeComponents, inspect };